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Introduction 


elcome to the world of collaborative coding! Whether you’re just start- 

ing your coding journey, building fairly complex programs, or building 

with a team of people, this book guides you in using one of the most 
used tools for collaborative code-writing; GitHub.com. With more than 31 million 
users and over 100 million repositories (projects) hosted, GitHub.com is the No. 1 
place to build and collaborate on code. 


About This Book 


Though you spend many hours sitting at your computer, alone, debugging and 
writing code, the ideal coding team includes more than just you. Hundreds of 
developers spent more than four years building World of Warcraft before its first 
release in 2004. Although occasionally you can build a big hit like Flappy Bird 
alone, in a couple of days, the norm for software development is that you will 
work with other coders, designers, testers, user experience experts, product man- 
agers, and sometimes hardware engineers to bring something to the hands of 
users. 


When you’re first starting out on complex coding projects, understanding effec- 
tive ways to collaborate can be daunting. This book introduces you to the world of 
open source development (the epitome of collaboration), as well as effective ways 
to work with one other person — or even yourself over the course of many years! 
(I don’t know about you, but Sarah from three years ago knows stuff that Sarah 
from today can’t remember, and Sarah from today has more experience than 
Sarah from three years ago.) 


GitHub For Dummies is written as a reference guide. Each part introduces you to a 
different aspect of collaborative coding. So if you’re experienced in using GitHub, 
but you’re new to the open source community, you can jump to Part 5 and skip 
some of the GitHub basics. 


Introduction 1 


As you explore each part of this book, keep the following points in mind: 


>> Words that are being defined appear in italic. 
>> Code and URLs (web addresses) are shown in monofont. 


>> Command sequences using onscreen menus use the command arrow. For 
example, when working in Scratch, you can open a new project as follows: 
From the menu bar, choose File > New. 


>> The figures you see in this book use Mac and Chrome. We provide some tips 
when what you see on a Windows PC may be different, but you should see 
the same things, regardless of which Internet browser you use. 


Foolish Assumptions 
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In this book, I make some assumptions that very well may be foolish, about you, 


your coding experience, and your goals. 


>» You're interested in and have had some experience with coding. You don't 
have to be an expert coder, but you have made a Hello World application (or 
the equivalent) in at least one programming language. 


>» You have patience and determination and are resourceful. When you're 
presented with a challenge, you can Google your way to finding a solution. 
This book guides you through GitHub.com as it exists at the time of writing it, 
but new features and workflows are being created, and part of your collabora- 
tive coding journey is to discover how to use those new features as they 
become available. 


>> You have experience with a keyboard and mouse on either Mac or Windows 
PC and have access to one of those machines. 


>> You're capable of using an Internet browser, such as Safari, Chrome, or 
Firefox, and you can type a URL to access a website, such as GitHub.com. 


>> You know how to install applications on your computer. Although we guide 
you through anything that is unique to the setup, you should know how to 
download and install an application without step-by-step guidance. 


GitHub For Dummies 


Icons Used in This Book 


TIP 





REMEMBER 


WARNING 


Throughout the margin of this book are small images, known as icons. These icons 
mark important tidbits of information: 


The Tip icon identifies places where we offer additional tips for making this jour- 
ney more interesting or clear. Tips can start you on a rabbit hole down another 
workflow, not covered in this book, or cover some neat shortcuts that you may not 
have known about. 


The Remember icon bookmarks to important ideas to help you work more 


effectively throughout this book. 


The Warning icon helps protect you from common errors and may even give you 
tips to undo your mistakes. 


Beyond the Book 


In addition to what you’re reading right now, this product also comes with a free 
access-anywhere Cheat Sheet that covers common commands and GitHub actions. 
To get this Cheat Sheet, simply go to www.dummies.com and search for “GitHub 
For Dummies Cheat Sheet” in the Search box. 


Other online resources also pair with this book: 
>» Online articles covering additional topics are available at www. dummies . com/ 
extras/github. 


>» Updates to this book, if any, can be found at www. dummies .com/extras/ 
github. 


>» GitHub Learning Labs are free, guided tutorials that can be installed and 
found at https: //lab.github.com. 
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Where to Go from Here 


GitHub is a tool used by millions of developers. The workflows that you discover 
in this book is just the beginning. As you become a more experienced coder, begin 
to collaborate on more elaborate projects, or join different companies and teams, 
you may encounter new workflows that use these tools in different ways. You 
should feel empowered to explore! Visit https: //help.github.com or https: // 
guides .github.com for guidance and don’t forget to follow the blog at https: // 
blog.github.com/ to stay up to date with all of the new features! 


4&4 GitHub For Dummies 


Getting Started 
with GitHub.com 


IN THIS PART... 


Discover how to use Git on your local computer to track 
changes in your project. 


Sign up for a free GitHub.com account. 
Explore GitHub.com resources and features. 


Install GitHub Desktop to manage the link between your 
local and remote projects. 


Install the GitHub Atom editor as a lightweight option for 
coding. 


Prepare for creating your own projects and contributing 
to others. 


IN THIS CHAPTER 


» Getting familiar with GitHub 





» Discovering Git 
» Signing up with GitHub.com 


» Exploring helpful resources 


Chapter 1 


Understanding the 
Git in GitHub 


hether you’re an experienced coder or a newbie starting out, learning 

how to work with others on code is critical to succeeding in the soft- 

ware industry. Millions of people around the world work together to 
build software, and GitHub is one of the largest tools to support a collaborative 
workflow. This chapter introduces you to the core tools you need to write code 
with other people. 


Introducing GitHub 


GitHub creates an environment that allows you to store your code on a remote 
server, gives you the ability to share your code with other people, and makes it 
easy for more than one person to add, modify, or delete code to the same file and 
project, while keeping one source of truth for that file (phew!). So what does 
that all actually mean? One of my favorite ways of explaining GitHub.com to folks 
who are new to the tool is to compare it to Google Docs — a place online where 
you can write code with other people and not have to email different versions back 
and forth. 


What makes GitHub work behind the scenes is Git. 
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Understanding Version Control 


Version control systems (also known as source control management, or SCM) are 
software that keep track of each version of each file in a coding project, a timestamp 
for when that version was created, and the author of those changes. 


Writing code is an iterative process. For example, when you’re building a website, 
you first may want to get some basic structure up before adding all your content. 
The best thing to do is to create a version of your website each time you have 

TIP something that works. That way, as you experiment with the next piece, if some- 
thing breaks, you can just go back to your previous version and start over. 


SCMs enable coders to make mistakes without worrying that they’ll have to com- 
pletely start over. Think of it like being able to click Undo, but instead of undoing 
each key press, you can undo an entire piece of the project if you decide you don’t 
like it or it doesn’t work. 


The basic workflow of coding with version control system support is as follows: 


1. Create a project, typically in a folder on your computer. 


2. Tell your version control system of choice to track the changes of your 
project/folder. 


3. Eachtime your project is in a working state, or you're going to walk away 
from it, tell your version control system of choice to save it as the next 
version. 


4. if you ever need to go back to a previous version, you can ask your version 
control system to revert to whichever previous version you need. 


You can use a version control system if you’re working alone on your own com- 
puter, but it gets even more interesting when you begin working with other peo- 
ple. (For more on working with other people, see the section “Git version control,” 
later in this chapter). 


For more information about version control, visit https: //git-scm.com/book/ 
en/v2/Getting-Started—About-Version-Control. 


Git Version Control 


GitHub, as the same would suggest, is built on Git. Git is a type of version control 
system, and it is free and open source, which means that anyone can use it, build 
on top of it, and even add to it. 
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TIP 


GitHub products make using Git easy, but if you’re curious, you can also use Git to 
track your solo projects on your computer. You can find a brief introduction to 
local Git commands for solo projects in the section “Try simple Git on the 
terminal”. 


Try simple Git on the terminal 


With the help of Git for Windows, using the terminal on Mac, Windows, or Linux 
computers is exactly the same. A terminal is an application that enables you to 
interact with your computer in a text-based way — in other words, instead of 
double-clicking and dragging, you type commands to navigate your computer. 


If you’re on Mac or Linux, a terminal is already installed on your computer. 
If you’re using a Windows computer, install Git for Windows, which is what this 
section assumes you’ve installed. Just go to https: //gitforwindows.org and 
click Download to gain access to Git Bash, an emulator that allows you to interact 
with Git just like you would on a Linux or Mac terminal. You also get Git GUI, 
which gives you a user interface for almost all Git commands you might type into 
Git Bash, and shell integration so that you can quickly open Git Bash or Git GUI 
from any folder. 


Many developers on Windows prefer to use PowerShell as their terminal environ- 
ment. You can use Git within PowerShell, but setting that up properly is outside 
the scope of this book. However, Phil, one of the authors, has a handy guide to set- 
ting this up at https: //haacked.com/archive/2011/12/13/better—git—with- 
powershell.aspx. 


First, find the Terminal application: 


» On Mac, you can click the magnifying glass at the top right of your desktop, 
type Terminal, select the terminal from the list of applications, and press 
Enter or click it. 


>> On Linux, press Ctrl-Alt-T all at the same time, and the terminal window 
opens. 


>> On Windows, click the Windows menu in the bottom right of your desktop, 
search Git Bash, select the Git Bash application from the list of search results, 
and press Enter or click it. 


When the application opens, type git --version in the terminal. If you have 
Git installed, you should see a version number, as shown in the following code 
(the $ should already be on the line, so you do not need to type it). Otherwise, 
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you can follow the instructions on https: //git-scm.com/book/en/v2/Getting- 
Started-Installing-Git. 


When using the command line, you have to be very careful about exactly what 
you’re typing. In the following code, the first instruction is for you to type 
git --version. You should note that a space appears between git and the rest of 

warning the instruction but no other spaces. You should also note the two dashes before 
the word version. They can be easy to miss, so be careful! 


For Mac or Linux, you should see something like this: 


$ git --version 
git version 2.16.3 
$ 


For Windows, you should see something like this: 


$ git --version 
git version 2.20.1.windows.1 


$ 


Next, using the terminal, go to your desktop and create a new folder called git 
practice. To do this, you should type the following commands: 


$ cd ~/Desktop 

$ mkdir git-practice 
$ cd git-practice 

$ 


If you type pwd, you should see that you are now in the folder git-practice, which 
is on your desktop. It might look something like this: 


pwd 
/Users/sguthals/Desktop/git-practice 


AHH 


Now, you can tell git to track this folder using the init command. 

$ git init 

Initialized empty Git repository in /Users/sguthals/Desktop/git-practice 
$ 
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Then make sure that you have a clean folder. You can check with the status 
command: 


$ git status 


On branch master 
No commits yet 


nothing to commit (create/copy files and use "git add" to track) 


$ 


Then, you can create a file to have Git start tracking and confirm the file is in the 
folder: 


$ echo "practicing git" > file.txt 
$ Is 

file.txt 

$ 


On Mac, you can open this folder in a Finder with the open <path> command: 


$ open . 


$ 
On Linux, you can open this folder with the nautilus <path> command: 


$ nautilus . 


$ 
On Windows, you can open this folder with the explorer <path> command: 


$ explorer . 


$ 


In this example, we put . as the <path> for each command. . tells the terminal to 
open the current folder. You could also use a different path with these commands 
to open other folders. 
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After the folder is open, double-click the file called file.txt, and the file opens 
with TextEdit on Mac, gedit on Linux, and Notepad on Windows. You can see that 
the words “practicing git” are actually there. 


Close the file. Now, you can tell Git that you want to save this as a particular ver- 
sion. Back in the terminal: 


$ git add file.txt 
$ git commit -m "Adding my file to this version" 
[master (root-commit) 8d28a21] Adding my file to this version 
41 file changed, 1 insertion(+) 
Create mode 100644 file.txt 
$ git status 
On branch master 
nothing to commit, working tree clean 


$ 


You can make a change to your file in the text file. Open the file again, change the 
text to say “Hi! I’m practicing git today!” and then click File Save and close the 
text application. 


When you go back to the Terminal to check the status of your project again, you 
should see that Git has noticed that the file has changed: 


$ git status 
On branch master 


Changed not staged for commit: 


(use "git add <file..." to update what will be committed) 
{use "git checkout —- <file>..." to discard changed in working directory) 
modi fied: file.txt 


no changed added to commit (use "git add" and/or "git commit -a" 


$ 


Commit this version of your file again and notice that Git recognizes that every- 
thing has been saved to a new version: 


$ git add file.txt 

$ git commit -m "I changed the text" 

[master 6d8@a2a] I changed the text 

4 file changed, 1 insertion(+), 1 deletion(-) 
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TIP 


TIP 


$ git status 
On branch master 
nothing to commit, working tree clean 


$ 


If your terminal starts to get too cluttered, you can type clear to clear some space 
and make it more visually appealing. Don’t worry; you can always scroll up and 
see everything you typed earlier! 


Say that you actually want to go see the original change; when you added “prac- 
ticing git”. First, get the log of all the commits you have made: 


$ git log 

commit 6d8Qa2ab7382c4d308de74c25669 f16d1407372d (HEAD -> master) 
Author: sguthals <sguthals@github.com> 

Date: Sun Dec 9 08:54:11 2018 -0800 


I changed the text 


commit 8d28a21 f71ec5657a2 £5421 e@3 faad307d9eec6F 
Author: sguthals <sguthals@github.com> 
Date: Sun Dec 9 08:48:01 2018 -0800 


Adding my file to this version 


Then ask Git to show you the first commit you made (the bottom most one). Make 
sure that you’re typing your unique commit hash. In this book, the hash starts 
with 8d28a2. Make sure you type the entire hash that appears in your Git log: 


Instead of typing the entire hash (and possibly having a typo), you can high- 
light the hash with your mouse, right-click and choose copy, and then after 
git checkout, you can right-click and choose Paste. Using the keyboard shortcuts 
Ctrl+C or %¥ -C doesn’t work 


$ git show 8d28a21 f71ec5657a2 £5421 e@3 faad307d9eec6f 
commit 8d28a21 £71ec6567a2 £5421 e03 faad3@7d9eec6F 
Author: sguthals <sarah@guthals.com> 

Date: Sun Dec 9 @8:48:01 2018 -0800 


Adding my file to this version 


diff --git a/file.txt b/file.txt 
new file mode 100644 
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index 0000000. .849a4c7 
--- /dev/null 

+++ b/file.txt 

@@ -0,0 +1 @@ 
+practicing git 

$ 


You can see that practicing git was added to the file in that original commit. 


For more information on how to use git on the command line, check out the 
following resources: 


>> The GitHub Git Cheat Sheet at https: //services.github.com/on-—demand/ 
downloads/github-git-cheat-—sheet . pdf 


>> The Visual Git Cheat Sheet at http: //ndpsoftware .com/git-cheatsheet . htm] 


>> The Git Docs page at https: //git-scm.com/doc 


Another couple resources for learning and understanding Git is https: //learn 
gitbranching. js.org and http://git-school.github.io/visualizing-git, 
which enable users on Windows to experience a similar workflow because they’re 
visualizations hosted on a website. The first link, learninggitbranching.js.org, is a 
good self-guided set of exercises, while the second link, git-school, is best used 
for folks who have a decent understanding of Git and want to explore what will 
happen in different scenarios, or for folks who have a more expert Git user guiding 
them. 


Git branching by collaborator 


Git is different from other version control systems because it has fast branching, 
shown in Figure 1-1. Branching is a Git function that essentially copies code (each 
branch is a copy of the code), allows you to make changes on a specific copy, and 
then merges your changes back into the main (master) branch. 


When you’re writing code, you will add files and commit changes to your master 
branch. Figure 1-1 outlines a specific workflow where two people are collaborating 
on the same file. Person 1 creates a new branch called MyBranch and makes some 
changes to the file. Person 2 also creates a new branch called YourBranch and 
makes some changes to the same file. You can see this change in box #1. 
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FIGURE 1-1: 
Example 
workflow for 
Git branches. 


REMEMBER 





T git checkout -b 2 git diff 3 git merge 










MyBranch Master Branch Master Branch 


MyBranch Master Branch 


Shang 





Master Branch 





4 git diff 5 


YourBranch Master Branch 


git merge 





YourBrat Master Branch Master Branch 














You can see the difference (called diff) between the master branch and MyBranch 
in Figure 1-1 in box #2. 


Then, Person 1 merges their changes with the master branch, as you can see in 
box #3. 


Person 2 has made their own changes, but before merging, they will make sure 
they have the most updated version of the master branch, which now has the 
changes from Person 1. The diff can be seen in box #4. Notice what text is in both 
files. 


Finally, Person 2 acknowledges that their changes will overwrite Person 1’s 
changes and merges their changes with master, making the final version have the 
changes from Person 2. Box #5 shows this final merge, with the master branch 
having the final changes. 


Figure 1-1 shows just one workflow that can exist when more than one person is 
working on code and is meant to describe branching. You can get a more in-depth 
overview on Git and branching at https: //git-scm.com. 


Git branching by feature 


Another common way to use branching is to have each feature that you develop 
be on a different branch, regardless of the collaborator who is building the feature. 


You can extend the idea of branching by feature to also have one branch that is 
your production branch. This branch is what your users will see. Then you can 
have a development branch, which is one that you can merge features into with- 
out changing what your users see. 
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TIP 


This type of branching allows you to build a lot of different features, merge them 
each into the development branch, make sure they all work the way you want, and 
then merge the development branch into the production branch when you know 
it’s ready for your users. 


Git branching for experimentation 


You can also create branches to test to see whether something works and then 
completely throw the branch away. 


This type of branching can be useful if you want to try a completely new layout of 
a website, for example. You can create three different branches, each with a dif- 
ferent layout. After you decide which layout you like best, you can simply delete 
the other two branches and merge the branch with your favorite layout into 
master. 


Git’s Place on GitHub 
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REMEMBER 


GitHub is a host for Git repositories. At some point, it is helpful to place your Git 
repository in a shared location as both a backup and a place where others can col- 
laborate with you on your code. As a Git host, Git provides all the features of Git in 
addition to a few extra useful services. 


On GitHub.com, projects, or repositories, are stored on remote GitHub servers. If 
you save all your code on GitHub.com and your computer crashes, you can still 
access it. 


Here is a list of some core Git features that GitHub supports: 


>> Repository: Each repository contains all the files and folders related to your 
project and gives you control of permissions and collaborators’ interaction 
with your code. 


>> Clone: When you want to make changes to your code, you will often want to 
create a copy, or clone, of the project on your local computer. The cloned 
project is still tightly connected with the version on GitHub.com;; it’s just your 
local copy. 


>» Fork: Forking a project is when you create your own copy of the entire project. 
When you fork a project, GitHub.com creates a new repository with your 
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copy of all the files. You can still suggest changes back to the original copy, but 
you can also take your version and go in a new direction. 


>» Branches: GitHub.com supports branching and even provides a useful 
tool — pull requests — to compare the diff between branches and merge 
branches. 


>> Commits: GitHub.com tracks all the commits that you push to its servers and 
gives you an easy interface for browsing the code at different branches and 
different commits. 


Signing Up for GitHub.com 


GitHub.com offers unlimited free public and private repositories for individuals. 
Free private accounts are limited to three collaborators. You can sign up for a paid 
account to have unlimited collaborators and some Pro features. 


Public means that anyone can see your code, clone your code, and therefore use 
your code. GitHub is a huge supporter of open source software (OSS) and therefore 
encourages public, shared code. Open source software is more than just public, 
shared code (see Part 5). Because every line of code can be traced to an author, you 
still get credit for what you’ve written, but the goal is to keep the code available 
for anyone to use, extend, and explore. 


The following steps guide you through signing up for a free, individual GitHub. 
com account: 

1. Goto GitHub.com and fill out the Sign Up form. 

2. Choose the plan you want. 


For the purpose of this book, you can use the Free plan. You can always 
upgrade to a paid plan later if you decide you want to have more than three 
collaborators for your private repository and other pro GitHub features. 


3. Complete the brief survey. 


This survey helps GitHub understand who is using the software and helps 
them support workflows specific to their users. 


You're now at the home page, shown in Figure 1-2. 
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=) Pullrequests Issues Marketplace Explore A +7 B- 


Learn Git and GitHub without any code! 


Using the Hello World guide, you'll create a repository, start a branch, write comments, and open a 
pull request. 


Read the guide Start a project 





Browse activit Discover repositories 
Q) Our new Terms of Service and x y ý 


Privacy Statement are in effect. 








Pepositonss Discover interesting projects and people to populate 
your personal news feed. 


Your news feed helps you keep up with recent activity on repositories you watch 
and people you follow. 


You don't have any repositories yet! 


FIGURE 1-2: 
The GitHub.com 
home page when 
you're logged in. 


Explore GitHub 











Personalizing Your GitHub.com Account 


As you become a more experienced coder, you may want to reference your GitHub. 
com profile on your resume and job applications. More and more companies care 
more about your portfolio than a list of degrees or awards. For example, GitHub 
doesn’t require you to provide information on your education as part of the hiring 
process and instead asks for a link to your GitHub.com profile and/or portfolio. 


To complete your GitHub.com profile: 


1. Click the avatar icon in the top right corner and choose Your Profile. 
2. Click Edit Profile on the page that appears. 
3. Fill out the form on the Personal Settings page, shown in Figure 1-3. 
4. Click Update profile when you're finished. 


On the Personal Settings page, you can also adjust a number of different settings 
to continue personalizing your account. 
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FIGURE 1-3: 
The Personal 
Settings page. 


WARNING 





Personal settings 
Profile 

Account 

Emails 
Notifications 
Billing 

SSH and GPG keys 
Security 

Sessions 

Blocked users 
Repositories 
Organizations 
Saved replies 


Applications 


Developer settings 





Public profile 


Name 


Public email 
Select a verified email to display + 


You have set your email address to private. To toggle email privacy, go to email 
settings and uncheck "Keep my email address private." 


Bio 


You can @mention other users and organizations to link to them. 


URL 


Company 


You can @mention your company's GitHub organization to link it 


Location 


All of the fields on this page are optional and can be deleted at any time, and by 
filling them out, you're giving us consent to share this data wherever your user profile 
appears. Please see our privacy statement to learn more about how we use this 
information: 


Profile picture 


Upload new picture 








Account 


In Account settings, you can change your password, change your username, or 
delete your account (see Figure 1-4). 


Changing your username may cause unintended side effects, so it typically isn’t 
recommended. Just make sure that after you change your username that anything 
that you need to continue working still does. Follow links, test code, and run your 


applications again. 


Emails 


GitHub allows you to link multiple email addresses to your account. Notice that 
you can add email addresses, keep your email address private, and even block Git 
commands that may expose your email address (see Figure 1-5). 
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Account settings. 
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Personal settings 
Profile 

Account 

Emails 
Notifications 
Billing 

SSH and GPG keys 
Security 
Sessions 
Blocked users 
Repositories 
Organizations 
Saved replies 


Applications 


Developer settings 


FIGURE 1-4: 


Change password 


Old password 


New password 


Confirm new password 


Make sure it's more than 15 characters, or at least 8 characters, including a number, and a lowercase letter. Read our 
documentation on safer password practices. 


Update password _| forgot my password 


® Looking for two-factor authentication? You can find it in Security. 


Change username 


Changing your username can have unintended side effects. 


Change username 


Delete account 


Once you delete your account, there is no going back. Please be certain. 


Delete your account 





Personal settings 
Profile 

Account 

Emails 
Notifications 
Billing 

SSH and GPG keys 
Security 
Sessions 
Blocked users 
Repositories 
Organizations 
Saved replies 


Applications 


Developer settings 


FIGURE 1-5: 
The Email 





Emails 


sarah@thewecan.zone GALESA Not visible inemails Receives notifications | 


Add email address 


Primary email address 

Because you have email privacy enabled, sarah@thewecan.zone will be used for account-related notifications 
and 45721253+sarah-wecan@users.noreply.github.com will be used for web-based GitHub operations (e.g. 
edits and merges). 


sarah@thewecan.zone + Save 


Backup email address 
Your backup GitHub email address can be used to reset your password if you no longer have access to your 
primary email address. 


Allow all verified emails $ Save 


Please add a verified email, in addition to your primary email, in order to choose a backup email address. 


Keep my email address private 
We'll remove your public profile email and use 45721253+sarah-wecan@users.noreply.github.com when performing web- 
based Git operations and sending email on your behalf. If you want command line Git operations to use your private email 
you must set your email in Git. 


Block command line pushes that expose my email 
If you push commits that use a private email as your author email we will block the push and warn you about exposing your 
private email. 


Email preferences 


Receive all emails, except those | unsubscribe from. 





settings. 
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FIGURE 1-6: 
The Notifications 
settings. 


WARNING 


TIP 


Notifications 


Notifications can get really overwhelming. Though you can choose your level of 
granularity for receiving notifications per repository, this page creates your 
default preferences for notifications (see Figure 1-6). 





Personal settings Notifications 
Profile 
Choose how you receive notifications. These notification settings apply to the things you're watching. 
Account 
Emails Automatic watching 


When you're given push access to a repository, automatically receive notifications for it. 
Notifications Automatically watch repositories 
Billing When you're added to or join a team, automatically receive notifications for that team’s discussions. 


3 i 
SSH and GPG keys Automatically watch teams 


Securit eer 
y Participating 
Sessions Notifications for the conversations you are participating in, or if someone cites you with an @mention. 
# Email Web 
Blocked users 
itori P 
Repositories Watching 


Organizations Notifications for all repositories, teams, or conversations you're watching. 


% Email Web 
Saved replies 


Applications Vulnerability alerts 


When you're given access to security vulnerability alerts, automatically receive notifications whenever there is a 
potential vulnerability detected in code. 


¥ Ulalerts © = Web 


Developer settings 


Receive security alert notifications via email 
% Email each time a vulnerability is found 


Email a digest summary of vulnerabilities 








Email notification preferences 





We recommend not automatically watching repositories because any kind of 
activity that happens on any repository that you interact with will start to show up 
in your inbox, which turns out to not be helpful as you begin collaborating more. 


Click the Things you’re watching link at the top of the notifications settings page 
to check to see what you’re watching and therefore what notifications you may get 
from them. 


Billing 


You can upgrade your plan at any time to include Pro features, such as unlimited 
collaborators and advanced code review tools. You can make this upgrade happen 
on the Billing settings page, shown in Figure 1-7. In addition to upgrading your 
plan, you can also purchase Git LFS data and other Marketplace Apps. You can 
even put in coupons from your company, school, or affiliated organization. 
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FIGURE 1-7: 
The Billing 
settings. 


TIP 


FIGURE 1-8: 
The place to 
create SSH and 
GPG keys. 


TIP 





Personal settings Billing overview 


Profile 

Plan Free plan, unlimited public repositories 
Account 
Emails Git LFS Data $0 per month for 0 data packs — Learn more about Git LFS Purchase more 


Notifications 


Marketplace 
Billing Apps You have not purchased any apps from the Marketplace. 
SSH and GPG keys 
Payment E No payment method on file. E Add payment method 
Security 
Sessions Coupon You don’t have an active coupon. {Ê Redeem a coupon 
Blocked users 
. Extra info@ You have not added any additional information for your receipts. # Add information 
Repositories 
Organizations 
Saved replies Payment history 


Applications 


You have not made any payments. 
Developer settings 








Git LFS stands for Git Large File Storage. Some software development requires 
large files, such as game scenes in video game development, to be stored. Without 
Git LFS, you can upload files as large as 100MB. Anything larger requires Git LFS, 
which supports files up to a couple GB. 


SSH and GPG keys 


At some point, you may want to create an SSH or GPG key to encrypt your com- 
munication with GitHub and ensure a secure environment. You can do this in your 
settings, shown in Figure 1-8. 





Personal settings SSH keys New SSH key 
Profile 
There are no SSH keys associated with your account. 
Account Check out our guide to generating SSH keys or troubleshoot common SSH Problems. 
Emails 
Notifications GPG keys New GPG key 
Billing 
There are no GPG keys associated with your account. 
SSH and GPG keys Learn how to generate a GPG key and add it to your account. 











SSH keys enable you to connect to GitHub from your local machine without having 
to put in your username and password each time. GPG keys mark tags and com- 
mits that you make as verified, meaning that other people know that it was actu- 
ally you who push the changes. 
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TIP 


Another way to tell Git to remember your credentials is to use a credential 
helper. GitHub tends to recommend this over using SSH, especially for Windows 
users. For more information on how to set up this feature, visit https: //help. 
github.com/articles/caching-your-—github-password-in-git. 


Security 


Not only should your password be complex, but you should also consider enabling 
two-factor authentication. Two-factor authentication means that when you type 
the correct password, you’re asked to further verify that it is you who is attempt- 
ing to log in through an app or SMS. 


Sessions 


Sessions allows you to see every computer address, city, and country where you’re 
logged in or connecting to GitHub.com. 


Blocked users 


In the Blocked users settings, you can block users from all your repositories. 


Repositories 


The Repositories section lists all the repositories that you have created or been 
invited to as a collaborator. You also can leave repositories from this page. 


Organizations 


Organizations enable you to put GitHub users and repositories under similar set- 
tings. For example, you can grant admin rights to all repositories in an organiza- 
tion to the entire organization, instead of having to individually add each person 
to each repository. Although Organizations is out of the scope of this book, you 
can read about them on the GitHub Help page at https: //help.github.com/ 
articles/about-organizations. 
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FIGURE 1-9: 
The Saved 
replies settings. 


Saved replies 


Saved replies, shown in Figure 1-9, can be extremely useful for popular OSS. For 
example, if you’re building an extension to an application, a lot of folks may 
report problems with the application, not with your extension. You can write a 
saved reply to point folks to where they can provide feedback on the application 
when they find an error. 





Personal settings Saved replies 
Profile 
Saved replies are re-usable text snippets that you can use throughout GitHub comment fields. Saved replies can 
Account save you time if you're often typing similar responses. Learn more. 
Emails 
Notifications No saved replies yet. 
Billing 


SSH and GPG keys 
Sy Add a saved reply 
Sessions Saved reply title 
Blocked users 
Repositories . - 

Write Preview A Bi e OD zE ON aid 
Organizations 


Saved replies 


Applications 


Developer settings Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


ED Styling with Markdown is supported 











Applications 


You can connect three kinds of applications with your GitHub.com account: 


>> Installed GitHub apps: GitHub applications that you are using with your 
account. One example is GitHub Learning Labs. 


>» Authorized GitHub apps: Applications that you have authorized to access 
your account. One example is Slack. 


>> Authorized OAuth apps: Applications that you have authenticated with using 
GitHub credentials. One example is GitHub Desktop. 
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Developer settings 


The last section on the Settings page is Developer settings, which you use only if 
you’re building an application that accesses the GitHub API, which means the 
application needs to access GitHub data in some way. 


Three settings appear in this section: 


>> OAuth apps: Applications you have registered to use the GitHub API. 
>> GitHub apps: Applications that integrate with and extend GitHub. 


>> Personal access tokens: Similar to SSH keys, tokens that allow you to access 
the GitHub API without requiring authentication. 


Discovering Helpful Resources 


The GitHub.com help page (https: //help.github.com) has an extensive list of 
documents for every feature on GitHub.com. From the top-right avatar menu, you 
can click the Help link. From there, clicking Contact a Human takes you to the 
GitHub contact page (https://github.com/contact) where you can find the 
following resources: 


>» AFAQ 
22 Links to the help documentation 


>» Links to developer documentation for help on the GitHub API (https: // 
developer .github.com) 


>> The GitHub Learning Lab for guided GitHub exercises (https: //lab. 
github.com) 


>» The GitHub Community Forum, where you can ask questions and get answers 
from folks who work at GitHub and other community members (https: // 
github.community) 


>> A slew of other resources about your experiences on GitHub.com 


If none of those resources are helpful, you can visit https: //github.com/ 
contact and fill out a quick form to ask a specific question. 


CHAPTER 1 Understanding the Git in GitHub 25 


IN THIS CHAPTER 


» Touring GitHub.com 





» Installing GitHub Desktop 


» Installing Atom 


Chapter 2 


Setting Up Your 
Collaborative Coding 
Environment 


itHub has a lot of features to offer new and returning coders. A good way 

to get acquainted with all those features is to explore the GitHub.com web- 

site. This chapter not only gives you that overview, but also guides you in 
setting up your local machine so that you can start building. 


Exploring GitHub.com 


The home page of GitHub.com, shown in Figure 2-1, is a great starting point for 
many tasks, including starting your own project, learning about a topic, or explor- 
ing existing repositories. 
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FIGURE 2-1: 
The home page 
of GitHub.com. 


FIGURE 2-2: 
The top menu bar 
of GitHub.com. 


rw) Pullrequests Issues Marketplace Explore M +~ Re 


Learn Git and GitHub without any code! 


Using the Hello World guide, you'll create a repository, start a branch, write comments, and open a 
pull request. 


Read the guide Start a project 





@ Our new Terms of Service and x Browse activity Discover repositories 
Privacy Statement are in effect. 
pee Discover interesting projects and people to populate 


your personal news feed. 


Your news feed helps you keep up with recent activity on repositories you watch 
and people you follow. 


You don't have any repositories yet! 


Explore GitHub 


© 2018 GitHub, Inc. Terms Privacy Security Status Help Contact GitHub Pricing API Training Blog About 











The top menu bar, shown in Figure 2-2, is always available to you and is a direct 
link to the most important functions you need to perform. 


>> GitHub home page: If you click the GitHub logo in the top left of the browser, 
you return to the home page. Check out the sidebar “Mona Lisa Octocat” for 
more information on the logo. 


>> Search bar: The search bar on the top menu is pretty snazzy. Not only can 
you search all of GitHub, but as you start to use the site, it offers suggestions 
based on your most recent activity. These suggestions make it fast and easy to 
find the repository you were working on yesterday. 


Account menu 


GitHub logo Notifications 


Pullrequests Issues Marketplace Explore 





Search bar Quick pick 
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MONA LISA OCTOCAT 


The GitHub logo is a 2D rendition of an octocat — a cat with five octopus-like arms. The 


logo was found on iStock, a website where royalty-free digital images can be purchased. 


Simon Oxley, the original designer, is also known as the designer for the Twitter bird 
logo. Cameron McEfee then led the effort around creating an entire Octodex of 
Octocats, which you can see athttps: //octodex.github.com. 


Mona Lisa Octocat also has a verified Twitter account (see figure). You can follow her at 
https: //twitter .com/monatheoctocat to get all of the most up-to-date 
happenings. 


eo %¢ Oo B 


Mona Lisa Octocat® 






Tweets Following Followers Likes C=» 
59 27 3,090 166 


Tweets Tweets & replies Media 








@monatheoctocat t Mona Lisa Octocat Retweeted 

Hi. I'm M Dy ight Stephanie (Schatz) Friedman @she_travels - 4 Nov 2018 {v 
i, is jona ¿` You might recognize me 4 = Our daughter Eliza's first three-syllable word: Octocat. @github @natfriedman 

as @github's mascot R 


4 Ea © 39 
E] Joined September 2018 4 4 5 


t Mona Lisa Octocat F ed 


Tweet to Mona Lisa Octocat Q Joelle Panza @J anza - 31 Oct 2018 v 


Happy Halloween @github #octocat #octocatCostume #techieHalloween 





One of the most popular things Mona has release is the “Build Your Own Octocat” app, 
which you can find at https : //myoctocat .com/bui1d-your-octocat. | created one 
and found my inner super woman! 


To discover the full history of the Octocat, visit http : //cameronmce fee. com/work/ 
the-octocat. 
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» 


TIP 


» 


» 


» 


» 


» 


» 


Pull requests: The link to pull requests takes you to a list of all pull requests that 
you created, were assigned to complete, were mentioned in, or were asked to 
review. A pull request is a proposed change to the code of a repository. When 
first starting, you normally don't have anything in this section, but as you start 
interacting with collaborative repositories, you get an overview of any tasks you 
may want to attend to. For more on pull requests, see Chapter 3. 


If you click the Pull requests link, you might notice a ProTip, shown in Figure 2-3. 
The search bar for pull requests gives you several ways to specify a search to get 
exactly what you're looking for. In fact, an entire page (nttps: //help.github. 
com/articles/searching—issues—and-pul 1-requests) is dedicated to 
effective searching. You can find ProTips throughout GitHub.com, so be sure 

to look out for them. 





Issues: The list of issues is almost the same as the list of pull requests. The 
main difference between an issue and a Pull Request is that an issue is a 
report of a bug or a feature request. An issue doesn't contain a proposed code 
change like a pull request does and therefore doesn't require a reviewer. 


Marketplace: The marketplace on GitHub is a great place to find applications 
and tools that can help your collaborative coding workflow. For example, | 
have used AppVeyor, a continuous integration application, on projects. When 
you connect AppVeyor to one of your repositories, it continuously runs tests 
and deploys apps to make sure that every bit of code you're adding won't 
break what you've already built. 


Explore: The Explore link takes you to a list of things you may be interested in 
(see Figure 2-4). You may find events and opportunities that GitHub hosts or 
supports. For example, at the time we wrote this book, GitHub just released 
“The State of the Octoverse,” which presents a lot of interesting analytics 
about code on GitHub — for example, GitHub users made 1.1 billion contribu- 
tions in 2018! 


Notifications: The bell icon leads you to a list of your notifications. See 
Chapter 1 for how to change your notification settings. 


Quick pick: The add-sign icon provides you with a list of quick actions you can 
take at any time: create a new repository, import a repository from another 
SCM, create a gist (a quick way to share code, notes, and snippets), or create a 
new organization. 


Account menu: The account menu appears when you click on your avatar. 
Here, you can get to your profile, repositories, anything you've starred, gists 
you've created, the help documents, and settings and can sign out. 


PART 1 Getting Started with GitHub.com 


ws) Pullrequests Issues Marketplace Explore A +~ Rr 


Assigned Mentioned Review requests 


T1OOpen v 0 Closed 


is:open is:pr author:sarah-wecan archived:false 


Visibility ~ Organization ~ Sort ~ 


No results matched your search. 


You could search all of GitHub or try an advanced search. 


Q ProTip! Exclude everything labeled bug with -label:bug. 


FIGURE 2-3: 
ProTip found 
on the Pull 
request page. 








ProTip 


Pullrequests Issues Marketplace Explore 


À Give back to open 


The State of the 


Octoverse 


See reflections and analytics on this 
past year in code. 


source App 
Build your own Octocat 


Take a break from your build and create 
an Octocat that's all you. 


Contribute to the software 
community in December at 24 Pull 
Requests ®. 





Based on your interests 


FIGURE 2-4: 
Curated list of 
repositories on 
GitHub.com. 





@ oracle / docker-images 


Official source for Docker 
configurations, images, and 
examples of Dockerfiles for Oracle 
products and projects 


K 2637 P2397 


Popular on GitHub 


Trending repositories 


as aws-amplify / amplify-cli 


A CLI toolchain for simplifying 
serverless web and mobile 
development. 


* 502 bes 


Popular on GitHub 


E nim-lang / Nim 


Nim is a compiled, garbage- 
collected systems programming 
language with a design that 
focuses on efficiency, 
expressiveness, and elegance (in 
that order of priority). 


e195 P767 
Popular on GitHub 


{8 zachowj / node- 
contrib-home-assi 


Node-RED integration 
Assistant through Web 
HTTP API 


w39 P4 


Popular on GitHub 


Date range: This week + 
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FIGURE 2-5: 
My profile. 


WARNING 


Your profile is a public view of, essentially, your portfolio. To view your profile, 
click your avatar and then choose Your profile from the menu that appears. You 
can see my profile in Figure 2-5. 







Pull requests Issues Marketplace Explore A +~ Re 


Overview Repositories 0 Stars 0 Followers 0 Following 0 


Popular repositories 


You don’t have any public repositories yet. 





1 contribution in the last year Contribution settings ~ 

Sarah Guthals a A , , n: f 

Dec Jai Feb Mar Apr May = Jun Aug Sep Oct 
sarah-wecan 
I'm the author of GitHub For Wed 
Dummies and found of 
@thewecanzone, where we guide a 
novice coders through books, Learn how we count contributions. Less MEME More 


courses, and professional 


development workshops. A AE " A PNA “ 
This is your contribution graph. Your first E is for joining GitHub and you'll earn more as you make 


Edit bio additional contributions. More contributions means a darker green square for that day. Over time, your 
chart might start looking something like this. 
We have a quick guide that will show you how to create your first repository and earn more green 
42 @thewecanzone squares! 
© San Diego, CA 
® http://thewecan.zone EE Read the Hello World guide 


©® Joined a day ago 











The top menu bar of your profile offers quick links to your repositories, things 
you’ve starred, your followers, and anyone that you follow. Below that are reposi- 
tories that you’re often visiting and your contribution graph. The contribution 
graph tracks how much code you’ve written per day. You can choose to include 
contributions to private repositories and an activity overview, which is a new 
feature. 


The amount and frequency at which you write code is not the bar by which soft- 
ware development is measured. It is true that the more you practice, the better you 
will be, but the practice you do must be deliberate. Making random code changes 
every single day without challenging yourself, or giving yourself time to think, 
design, and plan the code you want to write, is much worse than missing a white 
square. 
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Getting to Know GitHub Desktop 





REMEMBER 


WARNING 


GitHub Desktop is a free, open source application that makes it easier for Mac and 
Windows users alike to manage repositories and GitHub connections on their local 
computer. 


The fact that Desktop is open source means that you can follow the development 
of new features, connect with the developers right on the actual repository where 
the application is being built, and even choose to add features you’re interested in 
having. 


You can find the repository at https: //github.com/desktop/desktop. 


To install the GitHub Desktop on your computer: 


1. 


Go to https: //desktop.github.com and click Download for the platform 
you're using. 


This book is written with examples using Google Chrome and a Mac. GitHub 
Desktop works on a Windows PC as well because it’s built using Electron, which 
allows it to work on both operating systems. 


After the download finishes, click the file that was downloaded. 
The file automatically unzips. 


On Mac, the GitHub Desktop application appears in your Downloads folder, 
next to the zip file. On Windows, the application immediately opens after you 
unzip the file. 


On Mac, drag the purple GitHub Desktop application into your 
Applications folder. 


On Mac, go to your Applications folder and double-click the GitHub 
Desktop icon. 


The application opens, shown in Figure 2-6. 


You may get an alert that you are trying to open an application that was down- 
loaded from the Internet. Click “Open” if this alert appears. 
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FIGURE 2-6: 
The GitHub 
Desktop 
application 
default view. 





g Current Repository 
No Repositories 


@ GitHub Desktop File Edit View Repository Branch Window Help 


No Repositories Found 


+ (mj E 
Create a new project and publish it to GitHub Add an existing project on your computer and Clone an existing project from GitHub to your 
publish it to GitHub computer 
Create New Repository 
Add a Local Repository Clone a Repository 


Alternatively, you can drag and drop a local repository here to add it. 





Setting up GitHub Desktop 


34 


Before you can use GitHub Desktop effectively, you have to do a few things to con- 
nect it to your GitHub.com account. If you do not yet have a GitHub.com account, 
go to Chapter 1. If you already have a GitHub.com account and have already down- 
loaded GitHub Desktop, you can set up GitHub Desktop with the following steps: 


1. 
2. 
3. 


Open the GitHub Desktop application. 

Choose File > Preferences. 

On the Accounts tab, click Sign In on the GitHub.com row. 
The Sign In dialog box, shown in Figure 2-7, appears. 


Type your username and password and click the Sign in button or click 
Sign in using your browser. 


When you click Sign in, all the dialog boxes close. 
Repeat Step 1 to re-open the preferences. 


Your account with your avatar, name, and GitHub username appears under 
the GitHub.com row, confirming that you have successfully logged in. 
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Preferences x 


Accounts Git Appearance Advanced 
—=——_—_ 


GitHub.com 


Sign in to your GitHub.com account to access 
your repositories. 


FIGURE 2-7: Enterprise 








The Sign in dialog If you have a GitHub Enterprise account at 
box for the work, sign in to it to get access to your 
GitHub Desktop repositories. 
application. 


6. Click on the Git tab. 
The information has been auto-filled for you. 

7. Onthe Appearance tab, choose Light or Dark. 
Screenshots in this book are in Light mode. 


8. Set other preferences, such as the Editor and usage data, on the 
Advanced tab. 


This book uses Atom and Visual Studio Code as example editors, but you can 
select whichever editor you prefer. 


| recommend agreeing to send usage data, which is checked by default. By 
leaving it checked, you help the GitHub Desktop development team under- 
stand how all users use the application and therefore make it better. 


If you do not have a GitHub repository on your computer yet, you can stop the 
setup here. If you do have a repository, see Chapter 4. 


While a team of folks at GitHub predominately does the development of GitHub 

Desktop, a part of their role is to support community members who want to con- 

tribute to the project. Don’t hesitate to reach out to the team on its repository at 
REMEMBER Nttps://github.com/desktop/desktop. 


Introducing Atom 


Atom is a free, open-source editor. Just like GitHub Desktop, Atom is built on 
Electron, making it work on Mac or Windows PC. Atom is extensible, meaning you 
can add your own features to it. 


You can take a look at what the Atom team at GitHub is working on by visiting the 
repository; https: //github.com/atom/atom. 
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Atom is a lightweight editor that shouldn’t take long to install. To install Atom, go 
to https: //atom. io and click Download. 


Just like with GitHub Desktop in the previous section, when Atom finishes down- 
loading, click to unzip the file. On Mac, the Atom application appears in your 
Downloads folder. Drag the Atom application into your applications folder. On 
Windows or Mac, double-click the application to open it. When you do, you should 
see what is shown in Figure 2-8. 





@ Atom File Edit View Selection Find Packages Window Help 





CEO] untitled 


untitled 


FIGURE 2-8: 
The Atom 
application 
default view. 





You may get an alert that you’re trying to open an application that was down- 
loaded from the Internet. Click Open if this alert appears. 


A G . 
cee Here are a few things that you should know about Atom: 


>> Updates: Each time you start Atom, make sure you check the bottom- right 
corner to see whether any updates need to happen so that you keep your 
software as current as possible. When you click the Update link, the Settings 
tab opens, and the packages appear on the screen. In Figure 2-9, you can see 
that | had previously installed the package teletype, which requires an 
update. After clicking Update to 0.13.3 or Update All if | have multiple pack- 
ages that need updating, we restart Atom. 


You can click the Squirrel icon to go to the Atom About page to ensure that 
your Atom editor is also kept up-to-date. 


TIP 
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@ Atom File 


Edit View Selection Find Packages Window Help 





FIGURE 2-9: 
the Squirrel icon 
takes you to the 

About page 

where you can 
update Atom. 


» 


TIP 


» 


» 





Settings 


X Settings 


Available Updates Update All 


Check for Up 


teletype 0 
Share e with team member: 


inr 


& 
& Update to 0.13.3 


Update 


Git and GitHub tabs: At the bottom, right, next to where the updates are, 
you can easily open the Git and GitHub tabs by choosing Packages ® GitHub > 
Toggle Git/GitHub Tab. 


You may notice that some menu items throughout Atom have keyboard 
bindings, such as the Git and GitHub tabs in Figure 2-10. Keyboard bindings are 
combinations of keys you can press on your keyboard to make something 
happen in a specific application. You probably already know some of these. 
For example, when you're browsing the Internet, you can type $8-T on a Mac 
or Ctrl+T on Windows to open a new tab. Finding ways to become more 
efficient in your coding, such as by using keyboard bindings, can be an 
effective strategy for you as you become more expert in your coding journey. 


Preferences: You can specify a lot of preferences for Atom. | don’t explain 
each one in this book, but | encourage you to browse them and really set up 
Atom to make it exactly right for you. You can find the preferences by 
choosing Atom Preferences (see Figure 2-11). 


Packages: You can install more than 8,000 Atom packages to make Atom 
most effective for you. You can find them under preferences or at https: // 
atom. io/packages. Going through each of these packages is beyond the 
scope of this book, but | encourage you to explore some and search them if 
you're ever feeling limited by your Atom experience. 
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Window Help 
Bracket Matcher 
Command Palette 
Dev Live Reload 
Git Diff 









Si aAa Vv 










Keyboard bindings 


Keybinding Resolver 
Markdown Preview 
Open On GitHub 
Package Generator 
Settings View 
Snippets 

Spell Check 
Styleguide 
Symbols 

Teletype 

Timecop 

Tree View 
Whitespace 


Toggle GitHub Tab ^®8 






YYYY YYTT YTN 


roject directory with a Git 
repository 


FIGURE 2-10: 
Keyboard 
bindings for 
toggling the Git 
and GitHub tabs. LF UTF-8 PlainText ‘A? €)GitHub ©Git(0) a% 





@ Atom File Edit View Selection Find Packages Window Help 
eee Settings 


X Settings 





Core 


Editor Core Settings 


affect behavior unrelated to text editing. 
dual packag y have th dditional found within their package 
rd in the Packages list 


URI Handling 
Keybindings 
Allow Pending Pane Items 
Packages 
Themes 


Audio Beep 


Install Automatically Update 
terete ES Close Deleted File Tabs 
Close Empty Windows 
FIGURE 2-11: 


The Atom Color Profile 
Settings page. [iii W Qeittus oct) $ 





If you’re looking for resources outside of this book, check out the Atom documen- 
tation at https: //atom. io/docs and the Atom Flight Manual at https: //flight- 
manual .atom. io. Both of these resources can help guide you through any problem 
REMEMBER YOU May encounter. If they don’t, you can reach out to the developers who work on 
Atom by visiting the open source repository at https: //github.com/atom/atom. 
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Starting Your 
First Solo 
Project 


IN THIS PART... 


Create a GitHub repository to store code. 


Explore GitHub issues, pull requests, and project 
boards to manage your code. 


Create a GitHub Pages website for a project. 


Sync your remote GitHub project with your local 
coding environment. 


Create a GitHubb repository specfically for creating a 
personal website. 


Add a blog to a GitHub Pages website. 


IN THIS CHAPTER 


» Touring a repository? 





» Creating a Hello World repository 


» Exploring repository issues, pull 
requests, and project boards 


Chapter 3 


Introducing GitHub 
Repositories 


lmost everything on GitHub.com revolves around a repository. 


In this chapter, you find out how you can set up a repository, interact with it, and 
create project boards and issues. 


Setting Up a Repository 


A GitHub repository is a folder with all the files needed for your project, 
including the files that track all the versions of your project so that you can revert 
back if you make a mistake. A repository on GitHub also tracks who can collabo- 
rate and how. 


To get a better understanding of what a repository is and how it is structured, you 
need to create your first GitHub repo: 


1. Goto the home page of GitHub.com by clicking the Octocat. 


A list of your repositories appears on the bottom left side of the screen. 
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FIGURE 3-1: 
The page to 
create a new 
repository. 


TIP 


2. Click the green New Repository button. 


The Create a New Repository dialog page, shown in Figure 3-1, opens. 





Create a new repository 


A repository contains all the files for your project, including the revision history. 


Owner Repository name 
Las sarah-wecany / HelloWorld v 
Great repository names are short and memorable. Need inspiration? How about supreme-doodle. 
Description (optional) 
This is my first repository! 
© |: | Public 
A= Anyone can see this repository. You choose who can commit. 
© Private 


| ) You choose who can see and commit to this repository. 


Initialize this repository with a README 
This will let you immediately clone the repository to your computer. Skip this step if you're importing an existing 
repository. 


Add .gitignore: None v Add a license: MIT License x ÇQ) 


Create repository 











3. Type the name of your repository in the Repository name 
text box. 


| named my repository HelloWorld. 

4. Type a short description in the Description text box. 

5. Select the Public radio button. 

6. Click the Initialize this repository with a README check box. 
You do not need to add a .gitignore. 


7. Choose a license from the Add a license drop-down list. 


If you're interested in finding out more information about licenses, see the 


nearby “Software licenses” sidebar. 


8. Click Create Repository. 


The home page of your repository appears. It should look similar to the 
one | created, which is shown in Figure 3-2. Notice that a markdown file — 
README.md — is already in the repository. Markdown is a lightweight 
markup language used to style the words that you write with a plain text 
syntax. You can make words bold, turn them into headers, and even create 
a table for data. 
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SOFTWARE LICENSES 


Software licenses are a really important part to collaborative coding. Whether you are 
putting your code up on GitHub.com to share with the world, or contributing to some- 
one else's code, you should know what is allowed and what isn’t. When you first create a 
new repo, you're given the option to attach a license to it, as you see in Figure 3-2. If you 
click on the question-mark, you will be taken to https: //choosealicense.com/, 
which explains the top three most common software license types. 


Œ â /https://choosealicense.com 





Choose an open source license 


An open source license protects contributors and users. Businesses and savvy developers won't touch a project without this protection. 


Which of the following best describes your situation? 


4h Ky 5 


I need to workina I want it simple and I care about sharing 
community. permissive. improvements. 
Use the license preferred by the The MIT License is short and to the point. It The GNU GPLv3 also lets people do almost 
community you're contributing to or lets people do almost anything they want anything they want with your project, except 
depending on. Your project will fit right in. with your project, including to make and to distribute closed source versions. 
distribute closed source versions. 
If you have a dependency that doesn't have a Ansible, Bash, and GIMP use the GNU 
license, ask its maintainers to add a license. Babel, .NET Core, and Rails use the MIT GPLvs. 


License. 
What if none of these work for me? 


My project isn't I want more choices. I don't want to 
software. choose a license. 


More licenses are available. 


‘There are licenses for that. Here's what happens if you don't. 


The two main license types used for collaborative, public software are the MIT License 
and the GNU General Public License v3.0 License. The MIT License allows people to do 
almost anything with the code they find in your project. This includes being able to take 
a copy, make changes (or not) and distribute it as a closed source version. That means 
that they can distribute the software as an application without giving their users access 
to the code. The GNU General Public License v3.0 License also gives folks access to 
copy, modify, and contribute to your project, but if they want to distribute their version, 
it must be public and open. The repositories in this book use the MIT License, but you 
can choose what you want to do with your projects. 
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sarah-wecan / HelloWorld @watchy 0 ksta 0 y o 





«<> Code Issues 0 Pull requests 0 Projects 0 Wiki Insights Settings 

This is my first repository! Edit 

Manage topics 
1 commit P 1 branch O releases 42.1 contributor 

Branch: mastery New pull request Create new file Uploadfiles Findfile KOTTO 

FAR sarah-wecan initial commit Latest commit 3681f89 just now 

README.md Initial commit just now 

README.md r 


This is my first repository! 


FIGURE 3-2: 
The home page 


of my HelloWorld © 2018 GitHub, Inc. Terms Privacy Security Status Help Contact GitHub Pricing API Training Blog About 
repository. 











In Chapters 4 and 5, you can create a website for yourself. This website can link 
back to your repository. 


Exploring Your Repository 


A repository has a lot going on, even when it’s as simple as the HelloWorld one 
that I created in the preceding section. The following sections walk you through 
an overview of everything on the repository. 


Top information 


At the top of the repository is the username of the author and title of the reposi- 
tory. When you fork a repository, you see the original author underneath for a 
quick link. To fork a repository is to make a copy of it, where the changes you make 
to your copy can be suggested to the original author. See Chapter 6 for a deep dive 
into forking a repository. 


To the right of your username are three buttons: 


>> Watch: You can choose what kind of notifications you want to receive based 
on the type of activity happening on this repo. 
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WARNING 


» 


» 


Star: Starring can help you quickly navigate to certain repositories, as well as 
give GitHub insight into things you're interested in so that recommendations 
will be more accurate for you. To access your starred repositories, just click 
your avatar on the top right of GitHub.com and choose Your Stars. 


Fork: If you are not the author of the repository, then you have the option to 
fork it. Chapter 6 goes into more detail on forks. 


We highly recommend choosing either Not watching or Releases only for the 
majority of repositories so that you only get notifications when you’re specifically 
mentioned or actively participating in a discussion on an issue or a pull request. 
Otherwise, your inbox will be filled with emails about every single action taken on 
the repository, which will get out of hand very quickly. If you notice this happen- 
ing, go to https: //github.com/watching and unwatch all or some of the reposi- 
tories you’re watching with a quick click. 


Tabs 


Seven tabs appear across the top of your repo. Each tab provides different features 
for the repo: 


» 


» 


» 


» 


Code: The Code tab is where you can find all your code and browse folders 
and files. You can click a file to view its contents or click the pencil icon to 
modify the file, right in your Internet browser. (See the upcoming “Code tab” 
section for more details.) 


Issues: Issues are a really neat feature for repos. Issues can help you track 
things you want to still make, problems you're having, or suggestions for other 
people. You discover how to create issues in the upcoming section “Using 
Issues and Project Boards.” 


Pull requests: Pull requests, also referred to as PRs, are similar to issues 

in that they have a title and a description, but they also have code changes 
that you're requesting to be pulled into the main branch. The safest way to 
contribute code is to create a new branch, make your code changes on that 
branch, and then request for that branch to be merged with the master 
branch. A PR gives you an interface for merging the two branches, showing 
you the diff between the files you modified and the ones that are on the 
master branch and giving you a place to have a conversation with collabora- 
tors on whether the code should be merged or changes should be made first. 
For more information on branching, see Chapter 1. 


Projects: You may already be familiar with project boards like Trello or 
Kanboard. GitHub has project boards linked directly with your repo. The 
best part is that the cards on a GitHub project board can be directly related 
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to issues or PRs and can automatically move when something happens. For 
more on project boards, see the section “Using Issues and Project Boards,” 
later in this chapter. 


>> Wiki: Wikis are a great place to store documentation, project status, and 
roadmaps for your project. It's a great go-to place for collaborators to see 
what is going on and where they can jump in to help! 


>» Insights: The Insights tab, shown in Figure 3-3, gives you an overview of 
all collaborators and actions happening on the repo. It’s really neat to see 
this tab on popular open source projects. For example, TensorFlow has 
had 158 contributors in the last month! 





O tensorflow / tensorflow © Watch» 8,568 K Star 116,370 Fork 70,455 
Code Issues 1,513 Pull requests 272 Projects 0 ll Insights 
Pulse November 10, 2018 - December 10, 2018 Period: 1 month ~ 
Contributors 
Community Overview 
Commits 
-e a 
Code frequency 195 Active Pull Requests 635 Active Issues 
Dependency graph 
1103 p 92 @& 370 @ 265 
Network Merged Pull Requests Proposed Pull Requests Closed Issues New Issues 
Forks à 
Excluding merges, 158 authors have pushed 400 


1,584 commits to master and 1,584 commits 300 
to all branches. On master, 3,972 files have 


FIGURE 3-3: changed and there have been 214,669 o ee ee ee ee ee e e m 
The Insights tab additions and 102,424 deletions. ®SREBCHRBRat ESAn 











>» Settings: The Settings tab is visible only if you have the right permissions on 
the repository. In this tab, you can decide who has access to what and how 
collaborators should collaborate. You can also integrate apps that tell you 
how much of your code is covered with tests. 


Code tab 


The Code tab, shown in Figure 3-4, has a lot of additional important metadata 
about your repo that will come in useful in future development: 
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FIGURE 3-4: 
The Code tab. 


Description and Topics Metadata Action buttons 








sarah-wecan / HelloWorld OQwatchy 0 wkStar 0 klo 





<> Code Issues 0 Pulljrequests 0 Projects 0 Wiki Insights Settings 


This is my first repository! Edit 
Manage topics 


D1 commit P 1 branch © 0 releases 42.1 contributor 
Branch: master ~ New pull request Create new file Upload files Find fie KOTTO 


à] sarah-wecan Initial commit Latest commit 3681f89 just now 


E) README.md Initial commit just now 


EA README.md 

















HelloWorld 


This is my first repository! 








» 


» 


» 


» 





README.md file Code 


Description and topics: At the top of the Code tab is a description and a 
place where you can put in topics to make your repository more discoverable. 
Adding topics is particularly important if you want to attract other coders to 
help you build your software. 


Metadata: This bar contains information and links to the number of commits, 
branches, releases, and contributors for the repo. 


Action buttons: On the left side of the repo is a drop-down menu where 
you can change which branch you're looking at or browse the files for a 
particular branch. The New pull request button allows you to quickly create 
a pull request. The best way to create a pull request is to switch to another 
branch, make some changes, and then click New pull request. On the right 
side are three buttons related to files: Create new file, Upload files, and Find 
file. Finally, you can click on the green Clone or download drop-down list to 
clone or download the code to your local machine (see Chapter 4). 


Code: At the bottom of the Code tab is a list of all the code in this repo. If a 
README . md file appears in this list, then the file shows up below the list. For 
any file, you can click the filename to go to a page where you can see the file 
and edit it if you want. 
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Modifying README.md 
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TIP 


REMEMBER 


I highly recommend that every project, whether public or private, have a 
README.md file at the top level. This file is often the starting point for anyone 
who wants to contribute to the code. 


The README.md file will often have the following sections: 


>> Project title and description 

>» Prerequisites for getting the project running on your local machine 

>> Instructions on installing the project (and any dependencies) 

>> Instructions on running tests to make sure that you haven't broken anything 
>> Instructions on deploying the project 

>> An overview of dependencies 


>> A link to the guide on how to contribute to the project, including a code of 
conduct 


>> The main authors or maintainers of the project 
>> Alink to the license 


>> Any additional acknowledgements 


PurpleBooth on GitHub has created a great template for a README.md at https: // 
gist.github.com/PurpleBooth/109311bbO361 f32d87a2. 


GitHub promotes a culture of sharing and open software development. In the 
sharing, it is important that each person acknowledge where they drew inspira- 
tion and what pieces went into helping them create what they have created. Soft- 
ware development rarely happens alone and, at this point, is always built on 
someone else’s work. Though you don’t have to specifically acknowledge the work 
that Grace Hopper, a well-known computer scientist who created the first com- 
piler and English programming language, did to promote high-level program- 
ming languages so that you’re not all writing in assembly anymore, you should 
always recognize that it’s a large, timeless community working toward building, 
creating, and pushing the boundaries of what you think is possible today. 


For simpler projects, a README.md file can also be the front page to your project. 
In this case, the project is a description of you, and the README.md file is essen- 
tially the entire project because it will contain the information about you! 
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Follow these steps to modify your README with a headshot and a short descrip- 
tion about things you love: 


1. Goto the Code tab of your repository and click the Upload files button. 


Steps 2 through 6 guide you through the page shown in Figure 3-5. 





O sarah-wecan / HelloWorld Owatchy 0 wk star 0 o 





= 


<> Code Issues 0 Pull requests 0 Projects 1 Wiki Insights Settings 


HelloWorld / 

















SADAN 


Drag additional files here to add them to your repository 


Or choose your files 





FN Commit changes 


Adding a Headshot 


FIGURE 3-5: © Commit directly to the master branch. 
The page to add ® M Create a new branch for this commit and start a pull request. Learn more about pull requests. 
a file to the P sarah-wecan-patch-1 








HelloWorld 
repository. 





2. Finda headshot of yourself (or any picture that you want to be on your 
README) and upload it using the drag box. 


Alternatively, you can click the Choose your files link and browse your files to 
find your photo. 


3. Type a title in the text box Commit changes. 
In this example, | added the title “Adding a Headshot.” 


4. Select Create a new branch for this commit and start a pull request. 


d 


Type a name for the branch, or you can leave the default name for the 
branch. 


| left my default name, which is sarah-wecan-patch-1. 
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FIGURE 3-6: 


The Open a pull 
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request page. 


6. 


Then click the Propose changes button. 


The Open a pull request page appears with your one commit to add a new 
headshot to your repo (see Figure 3-6). 








= sarah-wecan / HelloWorld Qwatchy 0 wWstar o F o 





«> Code Issues 0 Pull requests 0 Projects 1 Wiki Insights Settings 


Open a pull request 


Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks. 


ih) 


FN Adding a Headshot Reviewers 


i 


base: master» © compare: sarah-wecan-patch-1~ | v Able to merge. These branches can be automatically merged 


No reviews 








Write Preview MABi «OD zE% @RA 
Assignees 

This pull request is to add some descriptions and a headshot to my README.| No one—assign yourself 
Labels 
None yet 
Projects 
None yet 

Attach files by dragging & dropping, selecting them, or pasting from the clipboard. Milestone 
No milestone 

ED Styling with Markdown is supported Create pull request 
© 1 commit 3) 0 files changed 0 commit comments 22 1 contributor 


Commits on Jan 01, 2019 


FA sarah-wecan Adding a Headshot Verified 








go 


Add a short description to explain the change and then click the Create 
pull request button. 


The Pull request tab displays your pull request with a title, number, status, 
description, list of commits, and a check to see whether it can be merged with 
master, shown in Figure 3-7. 


Click the Code tab to go back to the code in your repo. 


Click the branch drop-down list and switch to the branch you created in 
Step 5. 


This step allows you to see your project as it looks in that branch. The changes 
you make added to that branch as you make them and therefore the pull 
request that you created in Step 6. That way, you can add your headshot and 
make all the changes to the README at once. 


You see the new branch you created. Next to the branch is a link to the pull 
request you created. This branch is associated with that pull request, so you 
can kind of think of them as the same things. You also see the picture that you 
uploaded in your list of files. 
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Code Issues 0 Ñ Pull requests 1 Projects 0 Wiki Insights Settings 








Adding a Headshot = 
MKCO Sarah-wecan wants to merge 1 commit into master from sarah-wecan-patch-1 
& Conversation 0 Commits 1 E Checks 0 Â Files changed 1 40-0 
a 
sarah-wecan commented just now Soar Reviewers 
No reviews 
No description provided. 
Assignees 
FR adding a Headshot Verified No one—assign yourself 
Labels 
Add more commits by pushing to the sarah-wecan-patch-1 branch on sarah-wecan/HelloWorld. 
None yet 
‘| @ Continuous integration has not been set up Projects 
Several apps are available to automatically catch bugs and enforce style. 
None yet 
| © This branch has no conflicts with the base branch : 
Milestone 


Merging can be performed automatically. 
No milestone 


E You can also open this in GitHub Desktop or view command line instructions. 
Notifications 





4x Unsubscribe 











3, write | Preview MBI 6 OD EES @WMA- You're receiving notifications 
because you authored the thread. 
1 participant 
FIGURE 3-7: 
Attach files by dragging & dropping, selecting them, or pasting from the clipboard. Ê Lock conversation 
The pull request 
` ` ED Styling with Markdown is supported Close pull request Ez 
description page 
for an open pu II Q ProTip! Add comments to specific lines under Files changed. 
request. 


10. Because your README file is still showing, click the little pencil so that 
you can change what the README says. 


If it exists, a README file always appears below the list of files. 


11. Using Markdown, write a little about yourself, including your career 
passions and some hobbies you enjoy. 


Figure 3-8 shows you an example of the type of information you may want to 
include. 


12. click the Preview changes tab above the text. 


A red line appears to the left of the first two lines to indicate they will be 
deleted (see Figure 3-9). Everything you wrote after that has a green line to the 
left of it to indicate that the text will be added to your description. 


13. When you're satisfied with your description, scroll to the bottom of the 
file editor, add a title to the commit, and commit to the same branch you 
just created. 


You see your README.md file in its final state. 


14. Click the HelloWorld link at the top where it says He] loWorld/README . md 
to return to your code home page. 
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FIGURE 3-8: 
The README . md 
file in edit mode. 


FIGURE 3-9: 
The README . md 
file in diff mode. 





H sarah-wecan / HelloWorld Owatchy 0 WkStar o YFork 0 





<> Code Issues 0 Pull requests 0 Projects 1 Wiki Insights Settings 
HelloWorld / README.md @  orcancel 
<> Edit file © Preview changes Spaces $ 2 $ Softwrap + 


1 #A little insight into Sarah Guthals 
Hi Everyone! My name is Sarah Guthals and I am the author of “GitHub for Dummies’. This README will give you a bit of 
information about me! 


4 ## My Career Passions 

5 I really love working in tech. Specifically, I love being in a position where I can help others build something amazing! 
Whether that's being a manager, or working with customers and relaying that information back to the developers, that is my 
sweet spot! I enjoy teaching and learning, so any role that enables me to flex my education muscles is the right role for 
me, that's why I really enjoy writing these books! 


## My Hobbies 
8 One of my favorite things to do is go to Disneyland - even if I didn't go on any rides, just walking around the park and 
feeling the magic is enough for me :smile: 











<> Edit file © Preview changes 


| HelloWorld 


This is my first repository! 


A little insight into Sarah Guthals 


Hi Everyone! My name is Sarah Guthals and | am the author of GitHub for Dummies . This README will give you a bit of 
information about me! 


| My Career Passions 
l really love working in tech. Specifically, | love being in a position where | can help others build something amazing! 
Whether that's being a manager, or working with customers and relaying that information back to the developers, that is 
my sweet spot! | enjoy teaching and learning, so any role that enables me to flex my education muscles is the right role 
for me, that's why | really enjoy writing these books! 

| My Hobbies 


One of my favorite things to do is go to Disneyland - even if | didn't go on any rides, just walking around the park and 
feeling the magic is enough for me Se 











15. add your headshot by clicking on the pencil above the README.md file 


and adding the following line: 


! [headshot] (sarah_pic. jpeg) 


Make sure that you put the name of your picture in place of sarah_pic. jpeg. 


16. Preview the changes. 


Your headshot now appears. You can see mine in Figure 3-10. 


17. Scroll to the bottom and commit your changes. 
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FIGURE 3-10: 
The README .md 
file in diff 
mode with the 
headshot added. 








<> Edit file © Preview changes 





A little insight into Sarah Guthals 


Hi Everyone! My name is Sarah Guthals and | am the author of GitHub for Dummies . This README will give you a bit of 
information about me! 





You have now made changes to your project. The only problem is these changes 
are still on their own branch, and not on the master branch. To find out how get 
your changes merged into the master branch, refer to the next section. 


Merging a Pull Request 


After you have all your changes in a pull request (see the preceding section), you 
can merge those changes into the master branch by following these steps: 


1. 


2. 


On the main Code tab, click the View #1 button to get to your pull 
request. 


My pull request page, shown in Figure 3-11, has three different commits. The 
original one is when | added my headshot to my repo. The next one is when 

| added the new text to my README.md file, and the third is when | added my 
headshot to my README.md file. (If you haven't added these items and would 
like to, see the section “Modifying README.md”, earlier in this chapter.) 


Click the Files changed tab to see all the changes made to this repo. 


Files that appear in red will be deleted, while the lines in green will be added. 
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Code Issues 0 1 Pull requests 1 Projects 0 Wiki Insights Settings 


Adding a Headshot #1 


ye G sarah-wecan wants to merge 3 commits into master from sarah-wecan-patch-1 


S& Conversation 0 Commits 3 E Checks 0 Ô Files changed 2 
sarah-wecan commented 41 minutes ago « edited ~ Owner M 


This pull request is to add some descriptions and a headshot to my readme. 


12] sarah-wecan added some commits 42 minutes ago 





A Adding a Headshot Verified 
E update README to include my passions and hobbies Verified! cf fcb8s 
FPR added a headshot to the readme Verified 7e 





Add more commits by pushing to the sarah-wecan-patch-1 branch on sarah-wecan/HelloWorld. 





@ Continuous integration has not been set up 
Several apps are available to automatically catch bugs and enforce style. 





6 This branch has no conflicts with the base branch 
Merging can be performed automatically. 


Merge pull request You can also open this in GitHub Desktop or view command line instructions. 


FIGURE 3-11: 
My pul 
request page. 




















3. (Optional) To change the way you see the diff, click the Diff Settings 
drop-down list and then click Split then Apply and reload. 


If you split the view, your screen changes (see Figure 3-12). 





Conversation 0 Commits 3 E Checks 0 Files changed 2 
Changes from all commits ~ File filter... ~ Jumpto..~ +10 -2 mmmm Diff settings ~ 
12 mEmE“ README.md | <> E Copypath Viewfie Cl v 
CE -1,2 +1,10 0 
1 — # HelloWorld 1 + ![headshot](sarah_pic.jpeg) 
- This is my first repository! a + 
+ # A little insight into Sarah Guthals 
å + Hi Everyone! My name is Sarah Guthals and I am the 


author of “GitHub for Dummies”. This README will give you 
a bit of information about me! 
5 + 
© + ## My Career Passions 
7 + I really love working in tech. Specifically, I love 
being in a position where I can help others build 
something amazing! Whether that's being a manager, or 
working with customers and relaying that information back 
to the developers, that is my sweet spot! I enjoy 
teaching and learning, so any role that enables me to 
flex my education muscles is the right role for me, 
that's why I really enjoy writing these books! 
8 + 
+ ## My Hobbies 
FIGURE 3-12: i@ + One of my favorite things to do is go to Disneyland - 
The diff in even if I didn't go on any rides, just walking around the 
park and feeling the magic is enough for me :smile: 





split view. 
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4. Inthe Conversation tab, scroll to the bottom of the pull request and click 
the big green Merge pull request button. 


The Confirm merge dialog box replaces the section with the Merge button 
from Figure 3-12, as shown in Figure 3-13. 





Adding a Headshot 


{wie} Sarah-wecan wants to merge 3 commits into master from sarah-wecan-patch-1 


Æ Conversation 0 © Commits 3 & Checks 0 À Files changed 2 
e 
sarah-wecan commented 41 minutes ago « edited ~ Owner 


This pull request is to add some descriptions and a headshot to my readme. 


Œ sarah-wecan added some commits 42 minutes ago 


à] Adding a Headshot Verified ef58e4 
A Update README to include my passions and hobbies Verified £ 
FR addea a headshot to the readme Verified 76 


Add more commits by pushing to the sarah-wecan-patch-1 branch on sarah-wecan/HelloWorld. 


wr) 


Merge pull request #1 from sarah-wecan/sarah-wecan-patch-1 


Adding a Headshot 
FIGURE 3-13: 


The dialog box 
to confirm the cance 


merge of the 














pull request. 
5. Click Confirm merge. 

You see a message that your pull request merge was successful, with an option 
to delete the branch (see Figure 3-14). 

FIGURE 3-14: 

The merge Pull request successfully merged and closed alos branch 
confirmation for You're all set—the sarah-wecan-patch-1 branch can be safely deleted. 
a pull request. 











6. Click Delete branch. 


Your pull request is merged, and the branch is deleted. Don't worry, if you 
need that branch back for some reason you can restore it. It’s nice to keep 
things tidy within the repository. 
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7. Click the Code tab to go to your code. 


You see the master branch with your picture and the changed README.md file. 


Using Issues and Project Boards 
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FIGURE 3-15: 
The page to 
create anew 

project. 


Issues on a GitHub repo are a great way to track the things you need to fix, add, or 
change. When you combine issues with project boards, you get insights into your 
project that would otherwise be hard to track. In this section, you create issues 


and project boards and change your README . md. 


Creating a project board and an issue 


To get started on issues and project boards, go to your repo on the Code tab and 


then follow these steps: 


1. Click the Projects tab and then click the Create a project button. 


The Create a new project dialog box appears, as shown in Figure 3-15. 





8 sarah-wecan / HelloWorld @Qwatchy 0 wWStar 0 o 
Code Issues 0 Pull requests 0 [M Projects o Wiki Insights Settings 

Organize your issues with project boards Learn More 

Did you know you can manage projects in the same place you keep your code? Set up a project 

board on GitHub to streamline and automate your workflow. 











2. Adda project name and description. 


3. Fromthe preloaded Template drop-down list, select a project template 
and click the Create project button. 


In this example, | chose Automated kanban as my project template. 


A project board appears with some To do cards to show you how things work 
(see Figure 3-16). 
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FIGURE 3-16: 

A blank kanban 
project board 
template. 


FIGURE 3-17: 

The automation 
settings for the 
To do column on 
a kanban project. 








sarah-wecan / HelloWorld 


Code issues 0 Pull requests o (Projects 1 Wiki Insights Settings 
Tracking Changes to HelloWorld 
‘Updated just now 


3 Todo + ©) In progress + © Done 


{E + Welcome to GitHub Projects `+ 
We're so excited that you've decided to 
create a new project! Now that youre 
here, let's make sure you know how to get 
the mast out of GitHub Projects. 

@ Create a new project 

@ Give your project a name 
Press the 7 key to see available 
keyboard shortcuts 
‘Add a new column 
Drag and drop this card to the new 
column 
Search for and add issues or PRs to 
your project 
Manage automation on columns 
Archive a card or archive all cards in a 
column 


Aded by sarah-wecan 


© Cards 


pree Manage Automated as In progress Manage Automated as 


Done 


Owahe 0 Sur 0 


< +Add cards 


isopen 


+ Add colur 





Search 


Manage 





4. 


Click the Manage button at the bottom of the To do column to open the 


dialog box to choose what automation should happen. 


Figure 3-17 shows the automation settings for the To do column. Every time an 
issue gets created, it is automatically added to your To do column. You create 


an issue in Step 8 of this section. 








Manage automation for To do 


Choose a preset to enable progress tracking, automation, and 
better context sharing across your project. 


Preset: To do ~ 


Move issues here when... 


Newly added 
Issues will automatically move here when added to this project. 


Reopened 
The In progress column is already using this rule. 


Move pull requests here when... 


Newly added 
The In progress column is already using this rule. 


Reopened 
The In progress column is already using this rule. 


Update automation 
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TIP 


TIP 


5. 


11. 


Click the Manage button at the bottom of the In progress column. 


A similar automation settings dialog box appears (see Figure 3-17). Every 
time an issue is re-opened after you close it, or a pull request is created or 
reopened, it appears in the In progress column. You see this card in the 
To do column if you revisit the project after Step 11 of this section. 


Click the Manager button at the bottom of the Done column. 


Similar to Figure 3-17, automation settings appear. Every time an issue or 
pull request is closed or a pull request is merged, the cards move from the 
previous columns to this column. You see this in Step 14 of the section 
“Closing an issue”. 


You can change the automation settings for these columns or add other 
columns. Check out https: //help.github.com/articles/configuring- 
automat ion-for—project—boards for more information on project board 
automation. 


Delete the cards that were automatically added to the To do column by 
clicking the three dots on the top right of each column and choosing 
Delete note from the drop-down menu that appears. 


The card disappears. You can then click on the three dots of the next card that 
was automatically added to delete it. 


On the Issues tab, click New issue. 


If you haven't previously dismissed the dialog box, Figure 3-18 shows the dia- 
log box that appears above the Issues tab. Issues and pull requests can have 
labels, which are useful when your're trying to sort through things that still need 
to be done. If you're going to contribute to an open source project, looking for 
help wanted or good first issue labels is a great way to get started in the 
community. (see Part 5 for more information on open source software). 


Add a title and description to the new issue and then, on the right side, 
assign yourself to it. 


Link this issue with a project by clicking Projects and choosing Tracking 
Changes to HelloWorld. 


After you choose it, you see it in blue under Projects, as shown in Figure 3-19. 
Click the Submit new issue button. 


Just like with the pull request, the issue has a title, number, status, description, 
and some metadata on the right side (see Figure 3-20). One interesting bit of 
information is that the number is #2 for this issue, even though it's the first 
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FIGURE 3-18: 
The page 
that shows all 
issues for the 
HelloWorld 
repository. 


FIGURE 3-19: 

A new issue 
linked to the 
project Tracking 
Changes to 
HelloWorld. 


issue you've created on this repo. That is because issues and pull requests 
follow the same numbering, so the pull request was #1, this issue is #2, and 


any pull request or issue you open next will continue with #3. 


After you create an issue, the card relating to it appears on your project board. 


To see the new card in the To do column, click on the project board link under 





Projects. 
B sarah-wecan / HelloWorld @Qwatchy 0 wkStar 0 YFork 0 
Code © Issues 0 Pull requests 0 Projects 1 Wiki Insights Settings 
Label issues and pull requests for new contributors Dismiss 
Now, GitHub will help potential first-time contributors discover issues 
labeled with EEE] or 
Filters ~ is:issue is:open Labels Milestones 
@OOpen v 0 Closed Author + Labels ~ Projects + Milestones + Assignee ~ Sort + 


There aren't any open issues. 


You could search all of GitHub or try an advanced search. 


Q ProTip! no:milestone will show everything without a milestone. 





PN 
Add your favorite books to README.md 





Write Preview AA B i 6 <> D 


One section that would be neat to add to this page is your favorite books. 


Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 





CD Styling with Markdown is supported Submit new issue 








Assignees 


FF sarah-wecan 


Labels 


None yet 


Projects 


Tracking Changes t... 


Milestone 


No milestone 
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FIGURE 3-20: 


The description 


60 


page of an 
open issue. 








Add your favorite books to README.md « CS 


sarah-wecan opened this issue just now - 0 comments 


PN r = e A il 
Write Preview MBI 60% SES @R G- | Milestone 
No milestone 
Notifications 
qx Unsubscribe 
You're receiving notifications 
Attach files by dragging & dropping, selecting them, or pasting from the clipboard. because you were assigned. 
i lose i 
CD Styling with Markdown is supported Close issue deers 


sarah-wecan commented just now Owner Assignees 
FR sarah-wecan 
One section that would be neat to add to this page is your favorite books. 
Labels 
None yet 


a E sarah-wecan self-assigned this just now 


Projects 
m FÌ sarah-wecan added this to To do in Tracking Changes to HelloWorld via automation just now 
To do in Tracking Changes t... 








Closing an issue 


The best way to close an issue is to create a pull request with changes to address 
what was written in the issue. Understanding the relationship between issues and 
pull requests can help you on your own projects and open source projects. 


To close out the issue, follow these steps: 


From the Code tab on your repo, click the pencil icon for the README . md 
file to edit the file. 


Add a section at the bottom of the README . md file with your favorite 
books. 


Scroll to the bottom of the page and add a title to the commit. 
Choose Create a new branch for this commit and start a pull request. 
Click Commit changes. 

Add a description to the pull request. 


Specifically, make sure that you write closes #2 on its own line. When you 
type #, GitHub suggests any issue or pull request that you have in this repo to 
auto-fill. 














Link the project to this pull request. 


You link the project to the pull request the same way that you link a project to 
an issue. (See step 10 in the section “Creating a project and an issue”, earlier in 
this chapter.) 
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FIGURE 3-21: 

The project board 
with an open 
issue and an 
open pull 
request. 


FIGURE 3-22: 
The diff of 
README . md 
showing the 
added text. 


8. 
9. 


Click Create pull request. 


Return to your project board. 


You see the card for the pull request in the In progress column, as shown in 


Figure 3-21. 








3 sarah-wecan / HelloWorld 


Code Issues 0 


Tracking Changes to HelloWorld Ga 
Updated 21 days ago 


1 Todo 
© Add your favorite books to 


README.md 
#2 opened by sarah-wecan 


Automated as Todo 


Pull requests 0 


M Projects 1 Wiki Insights Settings 
+ 1 In progress + © Done + 
1 Added my favorite books 
A #3 opened by sarah-wecan 
Manage Automated as In progress Manage Automated as Done Manage 

















10. click the pull request card title to preview the pull request. 


Click Go to pull request for full details to return to the pull request. 


11. Click the Files changed tab and then click View file. 


You see the README . md file with your last section added (see Figure 3-22). 





O Conversation © Commits 1 


jes from all commits = File filter... Jump to...» 





3 mmm README.md 


8 My Hobbies 





® Checks 0 


One of ay favorite things to do is go to Disneyland - even if I didn't go on any rides, 
just walking around the park and feeling the magic is enough for me :smile: 


Files changed 1 


Ditt settings ~ 


| Review changes ~ | changes + 


Copy path viewfile © v 


+3 -0 umm 


ol 


#8 My Hobbies 
One of my favorite things to do is go to Disneyland - even if I didn't go on ony rides, 


just walking around the park and feeling the magic is enough for me :snile: 


+ ## Hy Favorite Books 

+ I absolutely LOVE the Harry Potter books, they are so engaging and rich. what is even 
better is the community that has formed around it. Lately, I've boon listening to podcasts 
that do deep dives into the entire Harry Potter universe and it is so much fun! 


Q ProTip! Use n and p tonavigate between commits in a pull request. 
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12. Click the Back button on your browser. 


13. If you're happy with the changes, click the Conversation tab, click Merge 
pull request button, click Confirm merge button, and then click the 
Delete branch button. 


You can revisit the section “Merging a pull request,” earlier in this chapter, 
for more details on how to complete this step if you get stuck. 


14. click the Projects tab and choose the project that you created. 


Both of the cards have moved from the To do and In progress columns to 
the Done column. 
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IN THIS CHAPTER 





» Getting acquainted with GitHub 
Pages 


» Creating a project website 
» Preparing a website repo 
» Preparing your local computer 


» Discovering resources for building 
your website on GitHub.com 


Chapter 4 


Setting Up a GitHub 
Website Repo 


ne technology that truly pushed the boundaries of society and software 

development was the Internet. As the Internet became more embedded in 

everyday life, it brought new meaning, career opportunities, and ways to 
connect for millions of people. A more recent phenomenon enabled by the Internet 
is a set of sites categorized as social media. Social media profiles provide a way for 
people to express who they are, what their interests are, and how to connect with 
them. But social media creates new challenges. 


Personally, I have accounts on Twitter, Instagram, Snapchat, Facebook, and 
LinkedIn. I don’t feel comfortable sharing personal accomplishments (like having 
a baby) on my LinkedIn, but also rarely share minor professional accomplish- 
ments (like starting a new project) on my Instagram. For me, having a website 
gives me a place to point people to all of me, not just the version of me that fits 
the community of the particular platform I’m using. That way, if folks want to 
learn more about the new project I’m working on, they will head to my website 
where they may also stumble upon the fact that my daughter is now walking and 
reach out to me to suggest a walker that worked well for their child. This interac- 
tion improves my bonds and connections with people from all aspects of my life. 
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Others may use a custom website to still focus on a particular part of who they are, 
but they like having the control over what they share and how they do it. This 
chapter, along with Chapter 5, guides you through turning any project repo that 
you own into a website and creating your own website on GitHub.com. In a matter 
of minutes, you can have a website up and running without having to pay for 
additional services. 


Introducing GitHub Pages 


TIP 


REMEMBER 


GitHub Pages is a fast and easy way to make a website that is hosted on GitHub. 
com. The code in your repo will be the code running the website. Even better is 
that it’s much easier to style your websites with Jekyll, a free, open-source site 
generator that takes Markdown files and creates websites with support for themes. 


You can discover more about Jekyll at https: //jekyllrb.com or even check out 
what it’s up to on its GitHub repo (https: //github.com/jekyll/jekyl1). 


With GitHub Pages, you can create a website using Markdown or HTML/ 
JavaScript/CSs. 


If you need help remembering what you can do with Markdown, visit the 
Markdown GitHub Guide at https: //guides.github.com/features/master ing- 
markdown. 


Turning a Project Repo into a Website 


64 


GitHub Pages is a great tool that is integrated into GitHub.com. GitHub Pages will 
look for a README.md file on your master branch and use it as the landing page 
for your website, meaning you don’t have to do much to get it up and running! 
Just follow a couple short steps: 

1. Open a repository on GitHub.com. 


For this example, | use my Hel loWor1d repo that | create in Chapter 3. 


2. On the home page for the repo, click the Settings tab on the top right to 
open the Settings page. 


The Options Settings page, shown in Figure 4-1, appears. 
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FIGURE 4-1: 

The GitHub Pages 
section under 
repository 
settings. 


TIP 





3. 


Make this repository private 


//github.com/sa: 





Allow rebase merging 
Add all commits from the head branch onto the base branch individually. 


GitHub Pages 


GitHub Pages is designed to host your personal, organization, or project pages from a GitHub repository. 


Source 
GitHub Pages is currently disabled. Select a source below to enable GitHub Pages for this repository. Learn 
more. 


None ~ 


Select source 


lll theme using the master branch. Learn more. 
master branch a 
Use the master branch for GitHub Pages. 


master branch /docs folder 
Use only the /docs folder for GitHub Pages. 


Y None 
Disable GitHub Pages. 








From the Select source drop-down menu, change the source for GitHub 
Pages from none to master branch and then click Save. 


The web page refreshes. If you scroll back to the GitHub Pages section, you see 
master branch under Source. 


Choose a theme for your website. 


A new web page loads, as shown in Figure 4-2. Browse through the themes 
and choose one. For my example website for this book, | use the Time Machine 
theme. 


After you choose a theme for your website, click Select theme. 
You return to the Settings page. 
Visit your project website. 


Scroll back down to the GitHub Pages section on the Settings page for your 
repository, and you see a notification in green that your site has been pub- 
lished with a clickable URL. 


If you don't see that your site has been published, try refreshing the web page. 
Sometimes browsers will cache, and these changes won't appear immediately. 


Click the URL and view the website you just made. 
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Pull requests Issues Marketplace Explore 


| Cayman 


vide thumbna 


Cayman theme 


Cayman is a clean, responsive theme for GitHub Pages. 


View on GitHub Download .zip Download .tar.gz 


Text can be bold, italic, or strikethrough. 


Link to another page. 





FIGURE 4-2: 
The GitHub Pages There should be whitespace between paragraphs. 
website theme There should be whitespace between paragraphs, We recommend including a README, or a file with 
chooser. information about your project. 


Setting Up a Personal Website Repo 


To create a new repo that houses your own personal website, you need to set up 
your repo: 


1. Create anew repository and name it username. github. io, where 
username is replaced with your actual GitHub username. 


For example, the name of Sarah's repository is sarah—wecan. github. io. If 
you're unsure how to create a new repository, see Chapter 3. 


2. Make the repository public, initialize it with a README, choose a license, 
if you want, and then click Create Repository. 


If you're unsure whether you want a license, see Chapter 3, which describes 
the benefits of choosing a license. 


The page refreshes to the home page of your new repository. 
3. Createa project with the Automated kanban template. 


If you don't know how to create a project, see Chapter 3 for guidance. 
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At the top of your repo again, click the Settings tab and scroll down until 
you see the GitHub Pages section. 


Notice that it says your site is already ready to be published at a certain 
URL (mine is https: //sarah-wecan.github. io/). If you go to this URL, 
you should see a simple barebones web page with the contents of your 
README.m¢d file. If you get a 404, just wait a moment and refresh the page. 
It can take a few seconds for GitHub Pages to build your site. 


In the GitHub Pages section, click Choose a theme and then click 
Select theme. 


If you've already chosen a theme and want to change it, this button is labeled 
Change theme. After you choose a theme, you're taken to one of two pages, 
depending on which theme you chose. Either you're taken back to the Settings 
page, from which you can navigate back to your code and you see a_config. 
yml file with your theme information. In this case, you can skip Step 6. 
Alternatively, you're taken to the README.md file in editing mode, where the 
theme information has been added to the README. In this case, you should 
follow Step 6. In either case, the commit of the _config.ym1 file happens 
automatically, and that commit triggers GitHub Pages to rebuild your site with 
the theme applied. 


Commit your README.md file. 


Your README.md file has now been modified to include information about 
your Jekyll template. Scroll to the bottom, add a title to the commit message, 
and choose Create a new branch for this commit and start a pull request. Then 
click Propose file change. The page refreshes with a new pull request ready to 
be created. You can merge your pull request. Then you can navigate back to 
your code, and you see the __config.yml file as described in Step 5. 


Create a pull request with a more inclusive title. 
For instructions on creating a pull request, see Chapter 3. 


Change the title of the pull request to describe everything you want to do for 
this iteration of your website and add a description. For example, | added the 
following list: 


To create a basic website: 
— [ ] Add a theme 
- [ ] Add an index.md file with "Hello World" on it 


Link this pull request to the project and create the pull request. 


To ensure your project board automatically tracks the progress of your 
website, choose the project created in Step 3 on the right side of the pull 
request from the Projects section. Then click Create pull request. 
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TIP 


TIP 


9. 


10 


11 


12. 


13 


14 


15. 


Update the pull request when appropriate. 


The description of a pull request is not static. When you first create a pull 
request, you may have a list of things you want to do before merging the code 
into the master branch. You may also end up making changes throughout. 
Make sure to always revisit the description and make sure it is accurate. For 
example, if you're following these steps exactly, you have already chosen a 
theme, so you can check the first box. 


Verify the project board automation. 


Go back to the project board by clicking on the Projects tab at the top of your 
repo and notice that a new card is in the In progress column. This card has a 
checklist on it, just like the description of the pull request does, and you can 
see that one of two tasks has already been completed. 


Switch to the pull request branch. 


Go back to the Code tab of your repo and switch to the branch that is associ- 
ated with your pull request. Mine is sarah-wecan-patch-1. 


If you don’t know how to switch to a different branch on GitHub.com, see 
Chapter 3. 


Create an index.md file. 


On the top right of your code file list, click Create new file. Name the file 
index .md and add a header that says “Hello World!”: 


# Hello World! 


Commit that file to the same branch you've been working on, with a title and 
commit message. 


Update and merge the pull request. 


Go back to the pull request and check off the second check box. Because 
everything that you wanted to do for this pull request has been completed, the 
pull request can be merged. Click Merge pull request, Confirm merge, and then 
Delete branch. 


Verify the project board automation. 


The pull request shows in the conversation that it has been moved from the In 
progress column to the Done column. You can also go back to the project 
board. Notice that the card has moved to the Done column, and both checklist 
items have been completed. 


Verify the website was published. 


Go back to your URL (mine was https: //sarah—-wecan.github. io). You have 
a working website with the theme you chose. 
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If you don’t see the theme that you chose, try refreshing your web page. You now 
have a website that you can continue building and customizing as you do more 
TIP and have more to share with the world. 


Creating Issues for Your Website 


After you have a GitHub.com website repository (see preceding section), you can 
think through the sections you want to have on your website. Creating issues for 
everything you want to add or change about your website can help you plan and 
remember all the little things you want to change. 


Say that someone gives you a great suggestion. You don’t want to pull out your 
computer and make the change right then and there, but you can quickly jump on 
GitHub.com and create an issue to remind you to add it later. Creating an issue can 
also be useful if you are working on your website, and you’ve found something 
that is bothering you that you want to change. Instead of derailing what you’re 
already working on with a new task, you can just make a quick issue and get to it 
later. 


To get started with this planning phase, go to the Issues tab on your repo and click 
New issue. Create an issue for all the things you want to add to your website. 


In this book, I create four issues to use in my example: 


>> Change the title and tagline. The title and tagline of your website is currently 
something auto-generated. You probably want to change it to your name and 
some tagline that represents you. Create an issue, assigning yourself to it and 
linking it to your project board: 


Issue Title: Change the title and tagline 
Issue Description: Make the title and tagline something 
unique to you. 


>» Add sections to the website. Without even having to leave an issue you 
created, you can click New issue and create another issue to add in sections to 
your website, assign yourself to the issue, and link it to your project board. In 
my example, I've chosen to add three sections: 


Issue Title: Add a couple of sections to the website 
Issue Description: Add three sections to the website: 
- [ ] About Me 

- | ] Contact Information 

- [ ] Blog 
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» 


» 


Write a blog post. Because one of the sections is to add a blog to the website, 
you may also want to actually publish your first blog post. Make a new issue to 
remind yourself, assign yourself to the issue, and link it to your project board: 


Issue Title: Write a blog post about GitHub 

Issue Description: With a blog section ready to go, add a 
blog post that talks about your interactions with GitHub 
so far. 


Link your project repo. You can turn your project repo into a website, as 
described earlier in this chapter. Why not link that website from your personal 
website? Create an issue, assign yourself to the issue, and link it to your 
project board. Later, you can link to other projects that you contribute to or 
find interesting: 


Issue Title: Link to the Project Repo 

Issue Description: I've turned http: //github.com/sarah- 
wecan/HelloWorld into a website and I want to link 
that website from this one. 


Four issues now appear under the Issues tab of my website repo, as shown in 
Figure 4-3. They also appear on my project board in the To do column (see 


Figure 4-4). 
(ws) Pullrequests Issues Marketplace Explore A +7 à” 
© sarah-wecan / sarah-wecan.github.io Owatch~ 0 Star 0 F o 
Code  @Jssues 4 Pull requests 0 Projects 1 Wiki Insights Settings 
Filters ~ is:issue is:open Labels Milestones } New issue | 
@4Open v 0Closed Author~ Labels» Projects» Milestones Assignee Sort 
© Link to the Project Repo A 


FIGURE 4-3: 
The issue list for 
the website 





#5 opened 22 days ago by sarah-wecan 


© Write a blog post about GitHub 


#4 opened 22 days ago by sarah-wecan 


#3 opened 22 days ago by sarah-wecan F Oof 3 


© Add a couple of sections to the website A 


© Change the title and tagline 


#2 opened 22 days ago by sarah-wecan 


Q ProTip! Add no:assignee to see everything that’s not assigned. 








repository. 
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FIGURE 4-4: 

The project board 
for the website 
repository. 


ws) Pullrequests Issues Marketplace Explore A +7 Rr 


sarah-wecan / sarah-wecan.github.io Owatch~ 0 wk Star 0 o 





Code Issues 4 Pull requests 0 fil Projects 1 Wiki Insights Settings 











Sarah's Website Gl 


+Addcards GFullscreen =Æ Me! 
Updated an hour ago 
4 Todo abs © Inprogress + e 1 Done sp Cee 
© Change the title and tagline zs Ñ Creating the basic website 
#2 opened by sarah-wecan là] 2of2 


#1 opened by sarah-wecan 


© Add a couple of sections to the 
website 


0of3 
#3 opened by sarah-wecan là] 


© Write a blog post about GitHub 
#4 opened by sarah-wecan A 


© Link to the Project Repo 
#5 opened by sarah-wecan 





Automated as To do Manage as Done Manage 





as In progress Manage 








Setting Up Your Local Environment 


TIP 


This section assumes you already set up GitHub Desktop and Atom. If you haven’t, 
Chapter 2 can help guide you through this process. 


In this section, you get your website working so that you can modify files on your 
local computer instead of on GitHub.com. 


Modifying files on your local computer can be useful if you need to work on a 
project when you won’t have Internet access or if you need to browse a lot of files 
while editing files. 


Cloning a repo in GitHub Desktop 


The first step in modifying files on your local computer is to get your website repo 
onto your computer: 


1. Open GitHub Desktop and choose File > Clone a Repository on the 
menu bar. 


You see a dialog box with three tabs; GitHub.com, Enterprise, and URL. 
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A nice alternative approach to cloning a repository when you have GitHub 
Desktop is to click the Clone or Download button on the home page of every 
repository. When you click the button, you see a flyout that includes an Open 

TIP in Desktop button. Click that button to launch GitHub Desktop (if it's not 
already running) and clone the repository to your local machine. 


2. On the GitHub.com tab of the Clone dialog box, your repositories auto-fill 
for you from GitHub.com. 


If your GitHub.com repositories don't auto-fill in the Clone dialog box, it 
probably means you're no longer signed in to GitHub.com in GitHub Desktop. 
You can log in by choosing GitHub Desktop Preferences from the top menu 

WARNING bar. Click the Accounts tab and sign in. If it appears you're logged in but your 
repos are still not showing up, try signing out and signing back in. 


3. Choose your personal website repository and choose where you want it 
to be stored on your local machine. 


| chose the default path as the place to store the repository on my local machine. 
4. Click Clone. 


GitHub Desktop refreshes with your repo information included. 


Touring GitHub Desktop 


GitHub Desktop offers a variety of features to help you with your development and 
interactions with GitHub.com. You can check out the GitHub Desktop User Guides 
at https: //help.github.com/desktop if you need additional support beyond this 
book. Figure 4-5 highlights the top six features: 


>> Repository list: As you clone more repositories to your local computer, 
clicking the Current Repository drop-down list reveals all the repositories that 
you have on your local computer, enables you to quickly switch between 
them, and gives you a quick button to add a new one. 


>> Branch list: The branch list gives you a quick overview of all the branches that 
you have checked out on your local computer, as well as a button to quickly 
create a new branch. 


>> Pull request list: One the same drop-down list as the branch list, you see a 
second tab that lists all the pull requests that are open on this repo. 
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FIGURE 4-5: 


An overview of 


GitHub Desktop. 


WARNING 


Repository list Branch and pull request list Sync project button 











@ GitHub Desktop a Edit View Repository Branch Windoj 


a] Current Repository p Current Branch c Fetch origin 
sarah-wecan.github.io master ™ Last fetched 33 minutes ago 


j i 2 
s Summary (required) Would you like to open this repository in Finder 


Description 





v Help | 





Changes History 


0 changed files 


No local changes 








» 


» 





Changes and history list 


Sync project button: As you start to make changes and/or changes are made 
on the repo outside of what you're doing on your local machine, you will need 
to sync. Because Desktop hasn't detected any changes made on GitHub.com 
or your local computer, the option presents itself as a fetch to start. If you 
start to make changes on your local machine, you can choose to push your 
local changes to GitHub.com. If you start to make changes on GitHub.com, 
you can choose to pull those changes to your local machine. If you create a 
repository on your local machine and it isn’t on GitHub.com yet, you can 
choose to publish your project to GitHub.com. 


If you do not push your changes to GitHub.com, they won't be available for 
other people and if your computer were to crash, you would lose all your 
work. We highly recommended that you push your code often. 


Changes list: As you start to make changes to your code, the files that you've 
added, deleted, or modified show up in this changes list. You can click each 
file to see the diff to the right. When you're ready to commit to those changes, 
you can add a Summary and Description and click the Commit to master 
button. At that point, you can push your changes to the branch that you're on 
using the Sync project button. 
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WARNING 


You should always double check which branch you're on before you commit 
and push your changes. You can undo commits and pushes, but avoiding it is 
best because the process can get hairy really quickly. 


>» History list: Next to the changes you find the history of this repo. The history 
includes activity from your local machine that has been synced with GitHub.com 
and activity from GitHub.com that you may have never done on your local 
machine. When you click one of the events, you see a list of activity that happened. 


Opening your repo in Atom 


To edit your files on your local computer, you can use a number of applications, 
including Atom, Visual Studio Code, or even TextEdit. In this book, we use Atom. 


To open your repo in Atom: 


1. Open Atom. 
You see a blank window. 
2. Choose File Add Project Folder from the top menu bar. 
A file finder dialog box appears. 
3. From the file chooser, open the folder for your repo and click Open. 


Your project is now open in Atom. 


Touring Atom 


Atom is primarily a code editor, but it also has features that make coding on 
GitHub repos much easier. If this section doesn’t offer enough detail for every- 
thing you can do with Atom, make sure that you check out the docs. In particular, 
the Atom Flight Manual is always updated to reflect the newest features (https: // 
atom. io/docs). Figure 4-6 shows the top six features: 


>» File list: On the left side of Atom is a list of all the files that you have in your 
repo. If you click a file, it opens in the center code editing area. 


>> Code editor: To the right of the file list is the code editor where you can write 
or modify code. 
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FIGURE 4-6: 
An overview 
of Atom. 


» 


» 


» 


» 


Branch list: At the bottom right corner of Atom is a branch chooser. Right 
now, you are on the master branch of your repo. If you click the branch, a 
menu pops up, allowing you to choose between branches or create a 

new one. 


Sync project button: Atom supports syncing your project with what is on 
GitHub.com. 


GitHub panel toggle button: If you click the GitHub button, the GitHub panel 
appears in your Atom window. This panel specifically lists and supports pull 
request actions. 


Git panel toggle button: If you click the Git button, the Git panel appears in 
your Atom window as a second tab next to the GitHub panel. This panel 
specifically supports staging and committing changes, as well as viewing the 
history of changes on this repo. 


File list Code editor 


@ Atom File |Edit View Selection Find Packages Window Help 








= ~/Desktop/sarah-wecan.github.io 


Branch list 
Sync project button 
GitHub panel toggle button 


Git panel toggle button 
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Finding Resources for GitHub Pages 


Some amazing folks over at GitHub have dedicated all their time to supporting 
GitHub users in discovering and learning about all the features that GitHub offers. 
Beyond the static documentation, the GitHub Training Team offers Learning Labs. 


Learning Labs are a self-guided, automated tutorial that actually has you doing the 
actions on GitHub.com and not just watching a video or reading a tutorial. You can 
find great ones for GitHub Pages, all GitHub fundamentals, Markdown, HTML, 
and even running your own Open Source Community. Head over to https: //lab. 
github.com, authenticate with your GitHub credentials, to try some of these 
outlearning Labs. 
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IN THIS CHAPTER 





» Reorienting yourself with an existing 
project 


» Getting ready to contribute to an 
existing project 


» Adding headers and sections toa 
website 


» Creating a blog using GitHub Pages 


Chapter 5 


Creating a Website with 
GitHub Pages 


n this chapter, you can find effective strategies for reorienting yourself with an 
existing project, as well as specifics on building a website with GitHub Pages. 
The examples shown in this chapter assume that you have an existing GitHub 
Pages repository. If you don’t and want guidance in setting one up, see Chapter 4. 


You can follow along in this chapter in order to build a simple website on GitHub 
Pages or jump around to the various sections to a find out how to do a specific task. 


Jumping into an Existing GitHub Project 


Whether you’re revisiting a project that you started yesterday, one you worked on 
last year, or finding a new project that you’ve never worked on, there are quick 
and easy ways to get oriented with a GitHub project. In this section, you see exam- 
ples of reorienting with the GitHub Pages website repo that we create in Chapter 3, 
but the tips apply to any GitHub repo. 


To get started, make sure that you’ve opened your browser to GitHub.com and 


have signed in. If you need to create a GitHub.com account, you can read about 
how to do so in Chapter 1. 
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FIGURE 5-1: 
Places to find 


GitHub repos on 
the GitHub.com 
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home page. 


Accessing the GitHub.com repo 


On the left side of the GitHub.com home page is the list of repositories that you 
have recently opened, contributed to, or created. Directly above the list is a search 
bar for searching repositories. This search bar becomes more useful as you inter- 
act with more GitHub repositories because the list of repositories can grow large, 
especially if you belong to a big organization. 


At the top of the home page is another search bar that you can use to search for 
repositories, project boards, and teams (a feature of organizations beyond the 
scope of this book). By default, this top search bar is scoped to your current con- 
text. If you’re on GitHub’s home page, it searches all of GitHub. If you navigate to 
a repository on GitHub.com, the top search bar searches within that repository. 


The search bar always gives you the option to search all of GitHub.com no matter 


where you are. Figure 5-1 shows the three ways to find a specific repository you 
may be looking for and two places to find new repositories. 


Search repositories, projects, and teams Discover new repositories 










Pull requests Issues Marketplace Explore a 
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Search for repositories List of repositories 
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TIP 


FIGURE 5-2: 
Commit changes 
box when you 
have write 
permissions 
ona repo. 


After you find the repository you want to start collaborating with, click it. The 
repository’s home page appears. 


This chapter gives specific examples about contributing to the GitHub Pages 
website repo that you’re the owner of, so if you want to follow on specifically for 
that, choose the repo titled your-username.github.io. The repo we use in this 
example is sarah—-wecan. github. io. 


Verifying your permissions for the repo 


If you’re the owner or admin of a repository, you will see a Settings tab at the top 
of the repository’s home page. You will have complete control over the repository, 
including the ability to 


>> Invite collaborators 


>» Change the visibility of a repository from public to private or from private to 
public 


>> Delete the repository 


>» Archive the repository 


If you don’t see the Settings tab, you’re not the owner/admin, but you may have write 
permissions. To determine whether you do, you can attempt to make a change to a file 
by navigating to the file and clicking the pencil icon. If you’re able to make a change 
and are presented with a Commit changes box similar to the one shown in Figure 5-2, 
you have write permissions and were added as a collaborator for the project. 





Commit changes 


® < Commit directly to the master branch. 


1) Create a new branch for this commit and start a pull request. Learn more about pull requests. 


Commit changes Cancel 











If you attempt to make a change but see the warning and commit box shown in 
Figure 5-3, you do not have write permissions and are not a collaborator. You can 
still create issues and propose file changes to the repo, but you have to get approval 
from someone with more permissions than you. If you’re interested in how to 
contribute to projects that you don’t have write access to, see Chapter 6. 
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FIGURE 5-3: 
Warning 

and commit 
box when you 


have read-only 
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permissions 
ona repo. 
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O Editfile © Pre 





@ He: 
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| Propose file change 








— Read-only permission 
warning 


— Commit box for read-only 
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Orienting yourself with the project 


Whether you’re the owner, a contributor, or a new visitor to a repo, you need to orient 
yourself with the project before you start working in case additional issues, pull 
requests, or updates have been made since your last visit. Then you’re the only author 
on a private repo, review what needs to be done before you start so that you can begin 
something of the appropriate scope given the time you have to work on the project. 
You don’t want to start building an entire new feature set if you only have a couple of 


hours; exploring a bug or making some minor updates may be better options. 


To get oriented, or re-oriented, with a project, you should review four places on 


the repo: 


>> Read the README .md, CONTRIBUTING. md, and CODE_ 


OF __CONDUCT . md files. 


Unless you're working on your own project, you should always read through these 


three files at least to make sure that you understand 


how to set up the project 


on your computer, contribute effectively to the project, and interact with other 
contributors. Not every project will have all these files, but if they exist, you 
should read through them to ensure that you're a positive member of the project's 
community. You can find a good example of these documents on the GitHub 
Desktop open source project at https: //github.com/desktop/desktop. 
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TIP 


>> Survey project boards. If the project uses project boards, look at those 
boards. Click the Projects tab at the top of the repo and choose a project 
board. Each project board usually has a column of things in progress or that 
need to be done. If the project board has automation, then any changes to 
issues or pull requests (including new ones) will appear on the project board. 
In the example for this book, the Sarah's Website project board has four 
issues listed in the To do column. 


>» Read through issues. Especially on active projects, folks are likely to have 
opened new issues. Click the Issues tab at the top of the repo to see the list of 
open issues. You can sort the issues by most recently updated to see whether 
folks have commented on existing issues. The default sorting is by newest 
(meaning the issues that were most recently opened). If you're the repository 
owner, triage any new or updated issues. Triaging is when you sort and order 
items. (See the sidebar called “Triaging issues” for more information about 
how and why to triage.) The example for this book shows four issues that we 
opened to help track the progress on our website. No one else has opened up 
any new issues or commented on them since we last visited the repo. 


>> Review pull requests. Both passively and actively reviewing pull requests is a 
good idea before starting to work on a project because they represent the 
new, removed, or changed code that aren't yet a part of the master branch. 
Passively reviewing pull requests means to read through the most recently 
opened and modified pull requests and see what kinds of contributions to the 
project are in the pipeline. This review helps to make sure that you don't start 
working on something that someone else is either already working on or that 
may break or contradict something that someone else is already working on. 
If you detect a problem, you can add a comment to the discussion on the pull 
request. 


You can also actively review pull requests if have the proper permissions for 
the project (and, more importantly, if you're confident that you can evaluate 
whether the changes should be merged). You can start the review process by 
opening a pull request, clicking the Files changed tab, and then clicking the 
Review changes button at the top right of the pull request, shown in Figure 5-4. 
In the example for this book, no pull requests are open for our website. but we 
have one that is closed (the initial website template that we added). 


Chapter 11 covers the pull request review experience. However if you want to have 
an interactive experience where you get to review a pull request on your own 
project before doing it on someone else’s project, you can visit https: //lab. 
github. com/githubtraining/reviewing-pul1-requests, authorize, accept Terms 
and Conditions, install GitHub Learning Labs, and take the automated, self-guided 
learning lab built by the great folks at GitHub. You can also practice reviewing a 
pull request on a repo designed specifically for this book, which you can find at 
https: //github.com/thewecanzone/GitHubForDummiesReaders/pull1/2. 
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Start a pull request review 
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FIGURE 5-4: + The purpose of this document is to allow GitHub For 
Dummies reader to learn practice reviewing a pull 
The place to start request! 
a review of a pull +. or er: 
+ I am proposing this file to be added. 
request. 





TRIAGING ISSUES 


Just like with an emergency room full of patients, triaging issues is the process of sorting 
and classifying issues on your repo. Okay, triaging issues may not be just like an emer- 
gency room because the issues are hopefully not life-threatening, but they're often criti- 
cal for your project. If you're the owner of a repo on GitHub, we recommend spending 
the first 30 minutes of your day on a project triaging anything that may have come in 
since the last time you visited the repo. In the triage process, you should include at least 


© Apply labels. Issues and pull requests can have labels associated with them. A few 
must-have labels are 


bug: An issue that reports something that appears to be broken and should be 
addressed quickly 


good first issue: An issue that a new contributor could start with 


help wanted: An issue where the code owner is specifically asking for help from 
the community 


needs investigation: An issue with questions that need to be answered before a 
solution is known 


feature/enhancement: An issue that requests a new feature or change to the project 
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Some labels are added to a repo by default, including: bug, duplicate, enhance- 
ment, good first issue, help wanted, invalid, question, and wonttfix. You can delete 
labels you don't want to use. Other labels can easily be added. 


© Respond to comments. Some issues may have new comments since the last time 
you were on the repo. For example, if someone opened an issue and you applied 
the labelneeds investigation and asked for additional information from the 
person who opened the issue, you may want to check to see whether he or she 
provided you with any additional information first. Issues should remain active. If 
they go stale (as in folks stop commenting or making progress on them), they 
should probably just be closed. 


e Close stale issues. Any issues that have gone stale should be closed. One example 
of when closing an issue is appropriate is when it's been a few weeks since the per- 
son who opened the issue last provided information or you know for a fact that you 
don’t want to add a requested feature. Always comment on the issue before closing 
and let folks know why it was closed. These comments are also useful for your 
future self to remember why you closed an issue. 


Preparing Your Contribution 


TIP 


After you orient yourself with your project, you need to decide what you’re going 
to work on for your contribution. For the example in this book, we choose issue 
#2 in the To do column of the project board: Change the title and tagline. 


Other good candidates are any issues that were opened with the label bug, help 
wanted, or good first issue because these issues are typically urgent for owners 
or good entry points for contributors. 


This section assumes you already have a repo cloned onto your machine. The 
examples in this section use GitHub Desktop and Atom to resolve the issues. If you 
need guidance in cloning a repo or getting the project set up in GitHub Desktop or 
Atom, see Chapter 4. 


Creating a branch for your contribution 


Before you modify or add code to any project, whether a private solo project you 
own or a large open source project, we highly recommend creating a specific 
branch where all the code you write will be contained. Branching is a Git function 
that essentially copies code (each branch is a copy of the code), allows you to make 
changes on a specific copy, and then merge your changes back into the main 
(master) branch. 
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REMEMBER 


When you create a branch, Git doesn’t actually copy all the code, which would be 
time consuming and inefficient. Git does something way smarter, but the specifics 
of what it does aren’t important to day-to-day usage of Git, which is why we say 
Git creates a copy of the code. It’s not technically correct, but it’s conceptually 
correct. It’s a useful mental model for branches. 


Creating a branch for your changes gives you a safe space to try out solutions and 
make mistakes without threatening your project’s integrity. If your solution is 
taking you down a wrong path, you can simply delete the branch, create a new 
one, and start over. Creating a branch helps your master branch remain in an 
always working state because you only merge your code into the master branch 
when you’re confident it doesn’t introduce any new problems and/or accurately 
solves the problem you were targeting. 


Different projects and people use different nomenclatures for their branches. In 
this book, we use a short description of the code modifications to name our 
branches. The folks who contribute to Atom, which is an open source project 
hosted on GitHub, often put their initials in front of their branches before a short 
description. You can see this nomenclature on the Atom GitHub repo at https: // 
github.com/atom/atom/branches. Before creating a branch on a public repo, 
check out how other contributors have been naming their branches or see whether 
the CONTRIBUTING. md file contains any guidelines. 


This book uses GitHub Desktop to manage projects on your local machine and 
Atom as the primary text editor. If you need to set up these two applications, see 
Chapter 4. 


To create the branch for your contribution, follow these steps: 


1. Verify the repo you cloned. 


Open the GitHub Desktop application and verify that the top left drop-down list 
has your website repo selected. Figure 5-5 shows the repo correctly selected. 


2. Create a new branch. 


Click the branch drop-down list in the top center of GitHub Desktop and click 
the New Branch button (see Figure 5-5). When you click the New Branch 
button, a dialog box appears. 


3. Give your branch a name. 


Type a name for your branch. In our example, we use new-title—and- 
tagline because that is the change we plan to make. 
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4. Click Create Branch. 


The dialog box closes, and you switch to the new branch. Figure 5-5 shows the 
current branch as master, but when you complete this step, it should change 
to your new branch name. The button at the top right of GitHub Desktop also 
changes from Fetch origin to Publish branch. 


5. Publish your branch. 


Before making any changes to your branch, we recommend publishing your 
branch to GitHub.com. That way, as you start to modify or add code and push 
it to your branch, you won't lose any your work. Click the Publish branch 

TIP button on the top right of GitHub Desktop. When the branch has been 
successfully published, this button goes back to the Fetch origin button, 
just like it is in Figure 5-5. 


Branch you're currently on New Branch button 


Repository drop-down list Fetch, publish, and sync button 





€ GitHub Desktop Fil Edit View Repository Branch) Window Help 


2 Current Branch ~ |E Fetch origin 
master ast inute 


Branches Pull Requests 0 


Default Branch 











~ master 22 days ago 


FIGURE 5-5: 

The button to 
create a new 
branch in GitHub 
Desktop for a 
specific repo 


$ Choose a branch to merge into master 


6. Open your project in Atom. 


Open the Atom application and verify that your project folder is open. 

A tree-view of your project appears in the left hand column. Notice that the 
branch selector at the bottom of the Atom application window now shows 
the branch name. Figure 5-6 shows the correct branch checked out in Atom. 
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FIGURE 5-6: 
The branch 


selector in Atom 
showing that the 
correct branch is 
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checked out. 


TIP 


File tree view 


@ Atom File Edit View Selection Find Packages Window Help 


eee =) GitHub — ~/Desktop/sarah-wecan.github.io 





Project index.md x ES GitHub x © Git x 
E sarah-wecan.github.io # Hello World! Checked out pull request 


Your current branch has not moved from the repository's default 
branch 


D _config.ym! 


-© Make some commits to share your work with a pull request. 
B LICENSE 


Open pull requests 
README.md 














index.md 2:1 LF UTF-8 GitHub Markdown “A’| 7 new-title-and-tagline] OFetch Q)itHub oGit(0) 


Currently checked out branch 


If you click the branch selector in Atom and change the branch, the branch in 
GitHub Desktop correctly changes to the same branch, and vice versa! 


Confirming your branch is published 


Before writing code that you want to keep, confirm that you correctly published 
your branch and are able to push to the branch. If you’re working on the same 
project, on the same computer, then you most likely are still properly set up. But 
if you’re contributing to a project for the first time or you have just set up a new 
computer, you should consider confirming you’re able to contribute. 


This section shows you examples of contributing to the GitHub website 
repo https: //github.com/sarah—wecan/sarah-wecan.github.io using GitHub 
Desktop and Atom. 


To get started, follow these six steps: 


1 ə Click a file in the file tree in Atom. 


Th file opens in the editor. Figure 5-7 shows index .md open. 
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TIP 


FIGURE 5-7: 
Editing a file in 
Atom. 


2. Modify the file. 


Don't make a lot of changes at this stage because the goal is to confirm you're 
able to push changes to the branch that you published. 


3. Save the file. 


Choose File = Save to save your changes. When you click Save, The color of the 
file in the file tree changes, and the Git button changes to indicate that a 
change occurred (see Figure 5-7). 
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index.md © Git 
# Sarah's Website = Unstaged Changes = Stage All 
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= Staged Changes 


Commit to new-title-and-tagline 


FÑ Merge pull request #1 from sarah-wecan/sarah-weca... Undo 
FÑ Adding an index.md file 


FFA Adding a theme to my website 





LF UTF-8 GitHub Markdown "A? B new-title-and-tagline Fetch C)citHub | Git (1) | a 





Git button 


4. Open the Git tab by clicking the Git button. 


You see the changes in the unstaged area. 


5. Stage and commit the changes. 


Stage all commits by clicking the Stage all button and write a commit message. 
Then click Commit to master. Figure 5-8 shows this step. After you click the 
Commit button, your commit appears in the commit list below the button, and 
a button that allows you to undo the commit appears. 
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Commit message Staged Changes 
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Staging and | 
committing 


changes in Atom. Commit button Commit history Sync button 


6. Push and merge the changes. 


The Sync button on the bottom bar to the right of the branch name changes its 
action based on your current context. Prior to creating the commit in the 
previous step, the button was labeled Fetch (see Figure 5-8). It now is labeled 
Push 1 to indicate that you have one commit that you can push. Click Push 1 to 
push your changes to GitHub. Then open GitHub.com and go to the repository. 
In this example, the repository is https: //github.com/sarah—wecan/ 
sarah-wecan.github. io. You now see a suggestion to open a pull request 
(see Figure 5-9). 


Create and merge the pull request. Chapter 3 gives a brief introduction to how 
to merge a pull request, and Chapter 8 gives an in-depth view of what you can 
do with pull requests if you need additional guidance. 


Sometimes, pull requests can create merge conflicts. See the sidebar “Resolving 
simple merge conflicts” for insight on how to resolve them. 
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FIGURE 5-9: 
GitHub.com 
indicates when a 
branch is ready to 
be merged. 
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You can use the editor on GitHub to maintain and preview the content for your website in Markdown files. 


Whenever you commit to this repository, GitHub Pages will run Jekyll to rebuild the pages in your site, from the content in 








RESOLVING MERGE CONFLICTS 


Sometimes your branch can get into a state where GitHub.com can't determine how 
to properly merge the code. This conflict can sometimes happen when a complex 


sequence of events happens. First, you create 


a branch from the master branch. As you 


make changes to your branch, someone else makes changes to the master branch. You 
then stage, commit, and push your changes to your branch, without pulling the changes 
made on the master branch into your branch first. The changes that you made may 
conflict with the changes that were made on the master branch — for example, you 
changed the same line, but started from a different place. For example, say that when 


you create your branch, the line is 
Hello World!!! 
and you changed it to 


Sarah's Website 
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(continued) 


But someone else changed the line on the master branch to 
Hello Friend! 


When you create the pull request, GitHub gets confused. The commit shows that you 
changed code fromHello World! ! toSarah's Website, but the code that you're trying 
to merge says Hello Friend!, so it's unclear what should actually change. Rather than 
making a change for you that you don't intend to make, GitHub asks you what you want to 
do. When you create the pull request, instead of a button allowing you to merge the pull 
request, you are prompted with a button to resolve the conflicts. Clicking this button takes 
you to a new page that presents you with the line of code with two options (see figure): 


e Code in your branch (on top) 


e Code in the master branch (on bottom) 


(Æ) } p Pull requests Issues Marketplace Explore A +7 à” 


sarah-wecan / sarah-wecan.github.io O©watchy 0 kSstar 0 o 
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Confirming push works. #6 


Resolving conflicts between new-title-and-tagl. and master and committing changes > new-title-and-tagl.. 


1 conflicting file index .md conflict Prva Nexty itr 


[> <e<<<<< new-title-and-tagline 
D) index.md # Sarah's Website 
index.md 





| # Hello world! 


L >>>>>>> master 


You can edit the code by deleting the delimiter lines and choosing the line you want to 
keep. In our example, the final code looks like 


# Sarah's Website 


Then, you can click Mark as resolved and commit the changes to your branch. 
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Building Your Personal Website 


This section is following the example website repo that is created in Chapter 4 to 
show some basics on how to build a website. However, the tips shown in this sec- 
tion can be used for any website you build using GitHub Pages. 


Modifying the title and tagline 


To modify the title and tagline of your website, open the __config.ym1 file in Atom. 
Add two lines above the only line that is in the file, indicating the theme. Your 
code should look like this: 


title: <Your Name> 
description: <Your Description> 
theme: jekyl1—theme—cayman 


Adding sections to your website 


Adding sections to your website is made easy with Jekyll and GitHub Pages because 
you can use Markdown and HTML. First, include some social media usernames. 
Open your __config.ym1 file and add as many social media usernames as you want. 
In this example, we add a Twitter and GitHub username: 


title: Your Name 

description: Your Description 
twitter_username: Your Twitter username 
github_username: Your GitHub username 
theme: jekyl1—theme—cayman 


Then, open the index.md file and change the code to include 
sections. For example, our code looks like this:# My Projects 
Here are a list of projects that I am have been working on: 


# My Interests 
I'm interested in teaching novice coders about computer science! 


# My Blog 
I'm really excited to blog my journey on GitHub.com. 
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WARNING 


# Get in Touch 

<ul> 

<li><a href="https://twitter.com/{{ site.twitter_username 
}}">Twitter</a></li> 

<li><a href="https://github.com/{{ site.github_username 
}}">GitHub</a></1li> 

</ul> 


Save, stage, commit, and push your changes to your branch and then create and 
merge the pull request into the master branch. After a couple of minutes, refresh 
the website page to see your changes. 


Creating a blog 


Having a blog on your site is a great way for you to share your GitHub journey with 
others. As you start to discover and create, you can share what you learn and build 
with a community of people with similar interests. This section guides you through 
creating the blog posts and linking them from your index. md file. 


First, create a new folder called _layouts and create a file within that folder called 
post.html. The _layout/post.htm1 file should contain the following code to 
create a blog-style: 


layout: default 


<hi>{{ page.title }}</h1> 
<p>{{ page.date | date_to_string }} - {{ page.author }}</p> 


{{ content }} 


Make sure that you correctly name the folder _layouts. Jekyll searches for the 
_layouts folder for any custom layouts. Otherwise, it uses the defaults for that 
theme. You can change the name of the specific layout — for example, post .md — 
but it should match the layout metadata, as shown in the following code snippet. 


Using layouts and specific naming, Jekyll can extrapolate the title, date, and 
author to display that both on the blog post page and on the home page. 


Then, create a new folder called _posts and a file inside with the date and a title. 
Typically, blog posts are made with YEAR-MONTH-DAY-TITLE.md. For example, this 
code is in a file called _posts/2019-@1-@1-new-year .md: 


PART 2 Starting Your First Solo Project 


TIP 


layout: post 
author: sguthals 


Write your blog post here. 


Finally, in your index.md file, add the following code below the My Blog section: 


<ul> 
{% for post in site.posts %} 
<li> 
<a href="{{ post.url }}">{{ post.title }}</a> 
</li> 
{% endfor %} 
</ul> 


Save, stage, commit, and push your changes to your branch and then create and 
merge the pull request into the master branch. After a couple of minutes, refresh 
the website page to see your changes. 


Linking project repos 


You can link GitHub project repos to your website in the same way you link social 
media, described in the section “Adding sections to your website,” earlier in this 
chapter. Putting a link directly to a repo can be efficient. However, you can also 
create web pages for project repos as well, as described in Chapter 4. 


Open the index.md file and add the following code, replacing the URLs with links 
to projects you’re the author of. This code shows linking to a project repo web 
page and directly to a project repo: 


<ul> 

<li><a href="https://sarah-wecan. github. io/HelloWorld/" >Hello 
World Project</a></li> 

<li><a href="https: //github.com/thewecanzone/ 
GitHubForDummiesReaders">GitHub For Dummies Repo</a></1i> 

</ul> 


Out of scope for this book are a vast number of ways you can customize your 
GitHub Pages website. Jekyll and GitHub come together to offer a unique experi- 
ence that requires some coding, but handles a lot of the setup. To find out how to 
do something specific, start by visiting GitHub Help at https: //help.github. 
com/categories/customizing-github-pages. 
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Contributing 
to Your First 
Project 


IN THIS PART... 


Fork your first GitHub repository so that you can 
contribute your own code. 


Get unstuck when you've cloned and changed code 
before forking. 


Create effective commit messages to communicate the 
changes you've made. 


Create a pull request to start the process of your code 
being merged in. 


Explore effective pull request workflows. 


Review a pull request. 


IN THIS CHAPTER 


» Understanding forking 





» Forking a repository 


» Getting unstuck with forking 
and cloning 


» Contributing code via a fork 


Chapter 6 


Forking GitHub 
Repositories 


ore than likely, you will want to work on some repositories where you are 

not the owner or collaborator. In situations where you aren’t the owner 

or collaborator, you will have to fork the repo if you want to do anything 
other than browse the files. 


In this chapter, we explain what forking is, show you how to fork a repository, and 
compare forking to cloning and duplicating. We also discuss contributing code via 


a fork. This chapter also demonstrates how to get the code you want to contribute 
into a fork if you’ve already made some changes to a clone before forking. 


Introducing Forking 


A fork of a repository is essentially just a copy of the repository. In the spirit of 
open source, forking is a way to share with and learn from other developers. 
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TIP 


Developers can have many motivations for forking a repository, but three of the 
most common reasons are to 


>> Contribute to someone else's project 
>> Use someone else's project as a starting point 


>> Experiment with someone else's code without making changes to their project 


If you aren’t the owner or a collaborator on a project, you’ll have to fork the repo 
if you want to do anything other browse the files. If you plan on making any 
changes to a repo where you aren’t an author or collaborator, fork the repo first so 
that you’re in the correct state as you start to explore and modify the code. Don’t 
worry, though, if you forgot to fork — see the section “Getting unstuck when 
cloning,” later in this chapter, for help you. 


Prior to GitHub, a fork of an open source project tended to have a negative conno- 
tation. It wasn’t just a copy of the source code, but a split in the community. A fork 
implies a fork in the road, where one group takes the project in a new direction. 
For example, Joomla is a fork of the Mambo project by a group of people that felt 
like a company had too much control. In practice, forks tend to be good for the 
overall ecosystem because they introduce new ideas. In some cases, the best ideas 
in the fork make their way back into the original project, such as when EGCS, 
which forked from GCC, had its changes merged back into the GCC project. On 
GitHub, forks tend to be more like short-lived branches that are either merged 
back into the main code or deleted. 


Cloning, Forking, and Duplicating 


98 


When you clone a GitHub repo, you’re creating a local copy of the project on your 
computer. Forking a GitHub repo creates a copy of the repo on your GitHub.com 
account, and from there, you can clone the repo. A link between the original repo 
and the one you forked will remain, allowing you to pull changes made on the 
original repo into your copy and push changes that you make on your copy to the 
original copy. 


Duplicating a repo is when you make a copy that no longer has a link to the original 
copy. Duplication isn’t a usual part of an open source workflow because it makes 
it more difficult to push changes back into the original repository. Even so, dupli- 
cating a repo can be useful sometimes, such as when the original project is no 
longer active and you plan to keep the project alive with your fork. 
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Cloning a Repository 


FIGURE 6-1: 
GitHub.com 
error message if 
you don't have 
edit permissions 
on a repo. 


WARNING 


Any public repo can be cloned, and you can run the code on your computer and 
make changes to the code. But you won’t be able to push those changes back to the 
remote repo if you don’t have push permissions to the repo. Chapter 4 describes 
how to clone a repository in GitHub Desktop when you’re the owner. The process 
is the same whether you’re an owner, collaborator, or visitor. 


Before you clone a repository, you should verify that you’re able to push changes 
to it. The easiest way to verify this ability is to go to the repository home page. If 
you see a Settings tab on the right side of the home page, then you likely have push 
rights. If you don’t, you likely have to fork the repo first. Alternatively, you can try 
to edit a file on GitHub.com, and if you get the message shown in Figure 6-1, then 
you don’t have permission to directly contribute to the project. 


ow) j T Pull requests Issues Marketplace Explore A +r Br 


O thewecanzone / GitHubForDummiesReaders ©watchy 0 wWwStar 0 YFork 0 





<> Code Issues 0 Pull requests 1 Projects 0 Wiki Insights 


You're editing a file in a project you don't have write access to. We've created a fork of this project for you to commit your proposed changes to. 
Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request. 


GitHubForDummiesReaders / README.md &  orcancel 


<> Edit file © Preview changes Spaces + 2 ¢ Softwrap + 


# GitHubForDummiesReaders 











If you do end up cloning a repository where you don’t have permission to contrib- 
ute to it, you can end up making changes and not being able to push them. The 
section “Getting unstuck when cloning,” later in this chapter, gives steps for how 
to get out of this state. 


After you have a repository cloned on your local computer, you can view and mod- 
ify metadata about it in your terminal. Open the terminal and go to a directory 
where you have a GitHub repository. If you need an example, clone https: // 
github .com/thewecanzone/GitHubForDummiesReaders by typing 


$ git clone https://github.com/thewecanzone/ 


GitHubF orDummiesReaders 
Cloning into 'GitHubForDummiesReaders'’.. . 
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remote: Enumerating objects: 15, done. 

remote: Counting objects: 100% (15/15), done. 

remote: Compressing objects: 100% (15/15), done. 

remote: Total 15 (delta 4), reused @ (delta @), pack-reused @ 
Unpacking objects: 100% (15/15), done. 

$ cd GitHubForDummiesReaders 


You can verify where the remote/target repo is with the following command: 


$ git remote -v 


origin https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (fetch) 
origin https: //github.com/thewecanzone/ 


GitHubForDummiesReaders.git (push) 


If you cloned the same repo as we did, you see the exact same origin URLs for fetch 
and push. You should see that the remote repo is one owned by thewecanzone 
and not sarah-wecan. Alternatively, if you run the same command on a repo that 
you own, you should see your username. For example, if we run the command in 
the directory where I cloned my website repo that we create in Chapter 4, 
I would see 


$ git remote -v 


origin https: //github.com/sarah—wecan/sarah—wecan. github. 
io.git (fetch) 
origin https: //github.com/sarah-—wecan/sarah—wecan. github. 


io.git (push) 


If you try using the command on a Git repo that doesn’t have a remote origin 
(meaning it isn’t hosted on GitHub.com or any other remote place), you simply 
won’t get any information back. For example, in Chapter 1, we create a simple Git 
repo called git-practice. Running the command in that directory gives you 
nothing back: 


$ git remote -v 


Forking a Repository 


The goal of open source is to encourage collaboration among software developers 
around the world, so being able to contribute code to repositories where you aren’t 
the owner or an explicit collaborator is an important part of the GitHub workflow 
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REMEMBER 


FIGURE 6-2: 
A forked repo on 
GitHub.com. 


WARNING 





and mission. To become a collaborator of an open source project, you can reach 
out to the owner of the repo and request to be a collaborator. However, if the 
owner doesn’t know who you are, they probably won’t add you as a collaborator 
because that would give you push rights to the repository. You’ll have to gain their 
trust first. 


You don’t need the owner’s permission to fork their repository. You can make 
your contributions and share them with the owner to show how you can be an 
asset to the project. 


To fork a repo, go to the repo home page and click the Fork button at the 
top right. If you’d like, you can use https://github.com/thewecanzone/ 
GitHubForDummiesReaders to practice forking and contributing to a public repo. 


After you click the Fork button, the web page refreshes, and you see a slightly 
modified version of the repo, as shown in Figure 6-2. At the top of the repo, you 
see that the repo is attached to your account, but it still has a reference to the 
original repo. 


Crumb trail linking the forked repo with the upstream repo 


€ Œ @ GitHub, Incli[US] | https://github.com/sarah-wecan/GitHubForDummiesReaders 
we) h or jt Pull requests Issues Marketplace Explore 
forked from thewecanzone/GitHubForDummiesReaders 
<> Code Pull requests 0 Projects 0 Wiki Insights Settings 
This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! Edit 
Manage topics 
D 3 commits Ẹ 2 branches © 0 releases 221 contributor of MIT 
Branch: master» New pull request Create new file Upload files Find file 











If you’re part of multiple GitHub organizations, you’re asked to choose which 
organization you want to fork the repository to after you click the Fork button and 
before the web page refreshes. 


After you have your own, forked version of the repo, you can clone it on your local 


machine to start making changes. Chapter 7 goes over writing code and creating 
commits, which is the same process whether you’re on a forked repo or a regular 
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TIP 


repo. If you clone the repo using GitHub Desktop, your local git repository 
knows about your forked version (remote origin) and the original repo (remote 
upstream). 


The concept of a remote can be confusing to those new to distributed version con- 
trol systems like Git. When you clone a GitHub repository, you have a full copy of 
the repository on your local machine. You may be tempted to think the copy of the 
repository on GitHub is the canonical copy. However, there is no concept of 
canonical in Git. The canonical copy is whatever the people working on the project 
decide it is by consensus. Git does have the concept of a remote, which is a pointer 
to a copy of the same Git repository hosted elsewhere. Typically, a remote is a URL 
to a Git-hosting platform like GitHub, but it’s possible to be a path to a directory 
with a copy of the repository. When you clone a repository, Git adds a remote 
named origin with the location (usually a URL) from where you cloned it. But it’s 
possible to add multiple remotes to a Git repository to indicate other locations 
where you may want to push and pull changes from. For example, if you clone a 
fork of a repository, you may want to have a remote named upstream that points 
to the original repository. 


If you clone the repo using the command line, you may want to set the upstream 
remote, which we explain in the section “Getting unstuck when cloning without 
forking,” later in this chapter. You can see both the forked remote origin and 
original remote upstream if you run the git remote -v command in the directory 
where you cloned the repo: 


$ git remote -v 


origin https: //github.com/sarah—wecan/ 
GitHubForDummiesReaders.git (fetch) 

origin https: //github.com/sarah—wecan/ 
GitHubForDummiesReaders.git (push) 

upstream https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (fetch) 

upstream https: //github.com/thewecanzone/ 


GitHubForDummiesReaders.git (push) 


The origin, which is where you fetch/pull changes from and push changes to, has 
your username (sarah-wecan in this example). The upstream, which is where the 
original code is located, and where you eventually want to contribute the code 
you write back to, has the original author’s username (thewecanzone in this 
example). 


PART 3 Contributing to Your First Project 


Fetching changes from upstream 


Having the upstream repo linked to your forked repo is important. As you start 
making changes, you want to be able to fetch/pull any changes that are being 
made on the original code into your code to make sure that you have the most 
up-to-date version. 


For example, suppose that you forked and cloned a website project a week ago 
with plans to change the website’s About page. While you were working on those 
changes, someone else made a change to the About page. Their changes may con- 
flict with your changes, or they may introduce something new that you want to 
use in your changes. Pulling those changes into your local repository before you 
submit your changes back to the original repository makes sense. It reduces the 
chance that your changes conflict with the changes others are making to the About 
page and makes it more likely the owner can accept them. 


If you find yourself in a situation where you need to get the change from the 
upstream, original repo, you can go to the directory where your forked repo is 
and type 


$ git fetch upstream 
remote: Enumerating objects: 5, done. 
remote: Counting objects: 100% (5/5), done. 
remote: Compressing objects: 100% (3/3), done. 
remote: Total 3 (delta 1), reused © (delta @), pack-reused @ 
Unpacking objects: 100% (3/3), done. 
From https://github.com/thewecanzone/GitHubForDummiesReaders 
8404f3b..e02a4d2 master —> upstream/master 
$ git checkout -b new-branch 
Switched to a new branch 'new-branch' 
$ git merge upstream/master 
Updating 8404f8b. .e@2a4d2 
Fast-—forward 
README.md | 2 + 
4 file changed, 1 insertion(+), 1 deletion(-) 


These three commands fetch the changes from the upstream repo, ensure that 


you’re on your local, forked repo on a new branch, and then merges the changes 
from the upstream repo into your forked repo. 
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FIGURE 6-3: 
Original, 


upstream repo 
detecting a new 
branch from a 


104, 


forked repo. 





Contributing changes to upstream 


After you make changes and publish them to a new in your forked repository, 
you’re ready to suggest your changes to the original owner. If you go to the origi- 
nal, upstream repo on GitHub.com, your branch shows up on the home page, and 
GitHub asks whether you want to open a pull request to merge the changes with 
the original repo (see Figure 6-3). 


Upstream repo name 


Œ  @ GitHub, Inc.|[US] | https://github.com/th GitHubForDurr 


=) 1 T Pullrequests Issues Marketplace Explore 


H thewecanzone / GitHubForDummiesReaders @watchy 0 wWStar 0 YFork 1 


<> Code Issues 0 Pull requests 1 Projects 0 Wiki Insights 


This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! 


®3 commits P 2 branches © 0 releases 42 1 contributor sf MIT 








Your recently pushed branches: 


Ņ sarah-wecan:AddMyself (less than a minute ago) T Compare & pull request 
Create new file Upload files Find file Clone or download + 





Branch: master + New pull request 








Upstream repo detecting branch from forked repo 


On your forked repo on GitHub.com, your branch shows up, and GitHub asks 
whether you want to create a pull request for it (see Figure 6-4). 


Click the Compare & pull request button, and a pull request creation page gives 
you the option to request to merge your changes with the upstream repo or your 
forked repo (see Figure 6-5). Choose the upstream repo, add a comment, and click 
the Create pull request button. 


You see that the branch can be merged, but you have no way to personally merge 
the pull request is because you aren’t the owner of the target branch (upstream, 
original repo); only the owner (or a specified collaborator) has permission to 
merge code. Figure 6-6 shows the pull request on your repo without the option to 
merge. 
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FIGURE 6-4: 
Forked repo 
detecting a 
new branch. 


FIGURE 6-5: 
Forked repo 
detecting a new 
pull request with 
the option for 
upstream or 
forked. 


Forked repo name and crumb trail 


â GitHub, Inc. [US] | https://github.com/s 


Pullrequests Issues Marketplace Explore 


¥ sarah-wecan / GitHubForDummiesReaders ©watchy 0 
forked from thewecanzone/GitHubForDummiesReaders 


<> Code Pull requests 0 Projects 0 Wiki Insights Settings 





This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! Edit 


Manage topics 


®3 commits Y 2 branches © 0 releases 221 contributor ob MIT 


Your recently pushed branches: 


P AddMyself (less than a minute ago) T Compare & pull request 
Branch: master~ New pull request Create new file Upload files Find file [eft yg: li) h is 














Forked repo detecting new branch 


Options for target repo 















û GitHub, Inc. [US] ||https://github.com/thewecanzo 


Pullrequests Issues Marketplace Explore 


O thewecanzone / GitHubFotDummiesReaders ©watchy 0 wStar 0 YFork 1 





<> Code Issues 0 Pull requests 1 Projects 0 Wiki Insights 


Open a pull request 


Create a new pull request by comparjng changes across two branches. If you need to, you can also compare across forks. 


uu base fork: thewecanzone/GitHubForDu... ~ base: master~ | head fork: sarah-wecan/GitHubForDum... + compare: AddMyself ~ 


Choose a Base Repository matically mered. 


| | 








v thewecanzone/GitHubForDummiesReaders 


sarah-wecan/GitHubForDummiesReaders 





Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


Allow edits from maintainers. Learn more ate pull request 
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€ G â GitHub, Inc. [US] | https://github.com/thewecanzone/GitHubForDu 


we) Pullrequests Issues Marketplace Explore 





© thewecanzone / GitHubForDummiesReaders @©watchy 0 wkStar 0 Yrork 1 
Code Issues 0 Ti Pull requests 2 Projects 0 Wiki Insights 


Adding myself to the table cS 


tule] Sarah-wecan wants to merge 1 commit into thewecanzone:master from sarah-wecan:AddMyself 


X Conversation 0 Commits 1 ® Checks 0 Files changed 1 +1-0m 
2 z 
P sarah-wecan commented just now Reviewers 

No reviews 


I'm working through the GitHub For Dummies book and | wanted to add myself to the table! 


Assignees 
FPR adding myself to the table 785efb No one assigned 


Labels 
Add more commits by pushing to the AddMyself branch on sarah-wecan/GitHubForDummiesReaders. 


None yet 





Cv) This branch has no conflicts with the base branch 


$ — 
Only those with write access to this repository can merge pull requests. TENS 


FN Write Preview AA B i <> D 


None yet 











Milestone 


No milestone 


Notifications 


4« Unsubscribe 


You're receiving notifications 


h fil r ins | ing them, or from i rd. 
Attach files by dragging & dropping, selecting them, or pasting from the clipboard. DSA ERGI eeacd 














FIGURE 6-6: CD Styling with Markdown is supported Close pull request | Comment | 
2 participants 
Pull request 
without the : 
option to merge. Unmergeable pull request status tile 


As the owner of the upstream, original pull request, I can see the pull request and 
have the option to merge it (see Figure 6-7). If you’re creating a pull request on 
this repo, I will continually merge pull requests so that we can keep an up-to-date 
table of all the GitHub For Dummies readers! 


If you have a lot of changes that you want to add to your fork before requesting 
that they get merged into the upstream, original repo, then you can first create the 
pull request to target your forked repo instead of the upstream repo. This is a 

TIP change in what is shown in Figure 6-5. When you’re ready to merge your changes 
into upstream, you can create a new pull request to request the target of the merge 
be the upstream repo. 
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FIGURE 6-7: 

Pull request with 
the option to 
merge. 


@ GitHub, Inc. [US] | https://github.com/thewecanzone/GitHubForDummiesReaders/pull/3 


train-e7f68199 GitHub:lab 


=) s Pullrequests Issues Marketplace Explore 





O thewecanzone / GitHubForDummiesReaders ©watchy 0 wStar 0 YFork 1 
Code Issues 0 Ti Pull requests 2 Projects 0 Wiki Insights Settings 


Adding myself to the table Edit 


MEE sarah-wecan wants to merge 1 commit into thewecanzone:master from sarah-wecan:AddMyself 


& Conversation 0 Commits 1 ®% Checks 0 Files changed 1 +1-0 8 
EN 
P sarah-wecan commented 43 seconds ago First-time contributor Reviewers 
Suggestions 
I'm working through the GitHub For Dummies book and | wanted to add myself to the table! à] sguthals Request 
EÑ Adding myself to the table Assignees 


No one—assign yourself 


Add more commits by pushing to the AddMyself branch on sarah-wecan/GitHubForDummiesReaders. 


Labels 
4 This branch has not been deployed None yet 

No deployments 
Projects 





J None yet 
p @ This branch has no conflicts with the base branch 
| Merging can be performed automatically. Kiita 


No milestone 


| MEE E ame You can also open this in GitHub Desktop or view command line instructions. 


P4 , = 4) Subscribe 
rf) Write Preview i= § <= 
You're not receiving notifications 


Mergeable pull request status tile 


Notifications 














Getting unstuck when cloning 
without forking 


One common problem people run into is they forget to fork a repository before 
they try to contribute to it. The following scenario describes one example of get- 
ting into this situation. 


Here’s the scenario: You clone a repository onto your local computer, modify the 
code, commit changes to master, and are ready to push your changes. But then 
you get a scary-looking error message. You may get the message in Atom (see 
Figure 6-8), GitHub Desktop (see Figure 6-9), or in the terminal: 


$ git push origin master 


remote: Permission to thewecanzone/GitHubF orDummiesReaders.git 
denied to sarah-wecan. 
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fatal: unable to access 'https://github.com/thewecanzone/ 
GitHubForDummiesReaders.git/': The requested URL returned 
error: 403 






































esoo = Git— ~/Desktop/GitHubForDummiesReaders E 
Project README.md x © cit x E cittup x 
~ E GitHubForDummiesReadors 1 # GitHubForDummiesReaders 
>B 2 This is a repository where all GitHub For Dummies 
= * readers can add a link to their GitHub profile! 
© ucense 3 
4 | GitHub Handle | Fun Fact | 
5 | =-=- | --—-—- \ 
6 | @sguthals | I have two cats and a dog! | 
7 | @sarah-wecan | I have a baby! | 
8 
YZ Staged Changes F Unstage All 
No changes 
( > 
Commit message 
z 
FIGURE 6-8: 
me FFA Adding myself to the README.md Undo Now 
Push permission FFA Merge pu request #1 trom thowecanzonefsguthals-pateh-1 1M 
error message FÑ Adding a table of readers ™ 
in Atom. README.md 7:34 LF UTF-8 GitHub Markdown "A? P master #Push1 (C)citHub ©Git(0) af 
@ GitHub Desktop File Edit View Repository Branch Window Help 
Error 
© Authentication failed. You may not have permission to access the repository or the 
repository may have been archived. Open preferences and verify that you're signed in with 
an account that has permission to access this repository. 
FIGURE 6-9: 


Push permission 
error message in 
GitHub Desktop. 
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The error message tells you that you don’t have permission to push to this repos- 
itory. You should have forked the repository first. You also made the mistake of 
committing directly to master. As we recommend elsewhere in the book, it’s a 
good practice to make all your changes in a branch. 


To fix this mistake, you need to move your changes to a new branch, fork the repo, 
change the remote URLs for your local repository to point to your fork, and push 
your changes. This process can get tricky, but these steps can help you out of this 
predicament: 


1. 


Migrate your changes to a new branch. 


Right when you discover you're targeting the incorrect remote repository, you 
should move your changes to a new branch. You don't want to accidentally pull 
in changes from the upstream, original branch onto all the hard work you just 
finished. This step can get tricky, but luckily Phil has created a Git Alias to help. 
See the nearby sidebar “Creating a Git Alias” for help. After you have the git 
migrate alias, go to the directory where your repo is in your terminal and type 


$ git migrate new-branch 

Switched to a new branch 'new-branch' 

Branch 'master' set up to track remote branch 'master' from 
‘origin’. 

Current branch new-branch is up to date. 


Confirm that the new branch has been created: 


$ git status 
On branch new-branch 
nothing to commit, working tree clean 


You can also confirm that your commits are only in this new branch and no 
longer in the old branch by running a log command to compare the two 
branches: 


$ git log master. .new-branch —-oneline 


This lists the commits in new-branch that are not in master. The --oneline 
flag prints each commit on a single line, which is useful when you just need a 
summary of commits and not the full details. 


Set the upstream remote to be the original repo. 


To add an upstream remote to your repo, go to the terminal and type 


$ git remote add upstream https://github.com/thewecanzone/ 
GitHubF orDummiesReaders.git 
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Confirm that the upstream remote was added correctly: 


$ git remote -v 


origin https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (fetch) 

origin https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (push) 

upstream https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (fetch) 

upstream https: //github.com/thewecanzone/ 


GitHubForDummiesReaders.git (push) 


3. Fork the repo. 


Back on GitHub.com, go to the original repo and click Fork at the top right of 
the repo home page. The page refreshes, and you see your own version of the 
repo, referencing the original repo (refer to Figure 6-2, earlier in the chapter). 


4. Set the origin remote to be your forked repo. 


After you have your own fork of the repo, you can change your remote origin 
to be your version: 


$ git remote set-url origin https://github.com/sarah—wecan/ 
GitHubF orDummiesReaders.git 


You can also confirm that all your remote URLs are correctly set: 


$ git remote -v 


origin https: //github.com/sarah—wecan/ 
GitHubForDummiesReaders.git (fetch) 

origin https: //github.com/sarah—wecan/ 
GitHubForDummiesReaders.git (push) 

upstream https: //github.com/thewecanzone/ 
GitHubForDummiesReaders.git (fetch) 

upstream https: //github.com/thewecanzone/ 


GitHubForDummiesReaders.git (push) 


5. Push your branch to your forked version. 


You're now in the same state that you would be in had you forked the repo 
before cloning. Back in Atom, you can publish your branch. 


6. Createa pull request. 


And just like in Figure 6-4, earlier in this chapter, your forked repo detects a 
new branch and offers to have you create a pull request. 
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CREATING A GIT ALIAS 


A Git Alias is an easy way to automate and extend Git commands. If you're doing a lot of 
Git commands on the terminal, creating Git Aliases can make your software develop- 
ment more efficient. For example, in your terminal you can type 


$ git config --global alias.st status 


Now, instead of typing git status, you can type git st, and Git returns the current 
status of your repository. Getting rid of just four letters may seem a little silly, but it can 
end up making your Git command experience a lot more efficient over time. 


A Git Alias is a lot more powerful than just reducing the number of keys you have to 
press. Phil describes a tricky scenario in his blog post (https : //haacked.com/ 
archive/2015/@6/29/git-migrate) where you have to migrate the commits you've 
made on a branch to another branch. This migration is critical if you get stuck in the 
position where you've started working on a clone of a repository where you don't have 
write permissions, as we discuss in the section “Getting unstuck when cloning without 
forking,” earlier in this chapter. 


The Git Alias to migrate commits from one branch to another is complex. It is a few 
complicated steps all rolled into one simple git migrate command. To make this 
command accessible for you to use when you get stuck on an unforked clone, follow 
these steps in your terminal: 


$ open ~/.gitconfig 
$ 


Your .gitconfig file opens in your default editor. Add the following code to the bot- 
tom of your .gitconfig file: 


[alias] 
migrate = "!f(){ CURRENT=$(git symbolic-ref --short HEAD); 
git checkout -b $1 && git branch --force $CURRENT 
${3-$CURRENT@{u}} && git rebase —-onto ${2-master} $CURRENT; 


ae 


If your .gitconfig file already has an [alias] section, don’t retype that line. Save and 
close the .gitconfig file. 


(continued) 
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(continued) 


Now you can use the git migrate command to migrate commits from one branch to 
another branch! This Git command has one required parameter and two optional 
parameters: 


git migrate <new-—branch-name> <target-branch> <commit—-range> 


The parameter <new—branch-name> is required. This branch is where you'll move the 
commits to. If you don't specify anything else, then the migrate command will move all 
commits from the master branch to this new branch. 


The parameters <target-branch> and <commit-range> are optional. <target- 
branch> allows you to move commits from a branch other than themaster branch to 
the <new-branch-name> that you specify in the first parameter. <commit—range> 
allows you to specify which commits you want to move over. This parameter can be 
useful if you accidentally made one commit on the wrong branch, and you just want to 
move that one commit over to <new—branch-name> . 
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IN THIS CHAPTER 


» Committing code in a terminal 





» Creating a good commit 
» Writing a commit message 


» Committing other tools 


Chapter T 
Writing and 
Committing Code 


n this chapter, you write and commit code. The first part, writing code, is a very 

broad topic — too broad to be covered in this (or any single) book. The code we 

write in this chapter sets the stage for covering how to create good commits. 
Most of this chapter focuses on committing code. No matter what kind of code you 
write, the act of committing that code remains the same. 


The code example we use throughout this chapter may seem contrived and overly 
simplistic. That’s because it is contrived and simple. Don’t let the simplicity, 
though, distract you because the information in this chapter also applies to large 
code bases. 


Creating a Repository 


A commit is the smallest unit of work with Git. It represents a small logical group 
of related changes to the repository. A commit additionally represents a snapshot 
in time — the state of the entire repository can be represented by referencing a 
single commit. 


CHAPTER 7 Writing and Committing Code 113 


Before writing code, you need to create a local repository to store the code. In the 
following examples, we create a repository in a directory named best-example. 
Feel free to change best-example to a directory of your choice. Fortunately, this 
process is quick and painless: 


1. Open the terminal on your computer. 
If you don’t know how to do so, see Chapter 1 for guidance. 


2. Go to the directory where you want your project folder to be stored and 
y y y J 
type the following commands: 


$ git init best-example 
$ cd best-example 


The first command creates an empty Git repository in the specified directory, 
best-example. Because the best-example directory doesn't already exist, Git 
creates it. The second command changes the current directory to this new 
directory. 


Nearly every Git tutorial I’ve seen that covers initializing a Git repository does 
it in the current directory by calling git init with no parameters or git init . 
where the . represents the current directory. People can be forgiven for not real- 

TIP izing you can both create the repository directory and initialize it in one step by 
passing in the path to the new repository like we do here. In fact, you can combine 
both of these commands into a single command: git init best-example && cd 
best-example. This tip can help you gain the admiration and adulation of your 
less efficient peers! 


Writing Code 


After you’re in a Git repository directory, you can start adding files. (If you aren’t 
in a directory, see the previous section, “Creating a Repository” where we created 
the best-example directory.) 


For this example, you create three files by typing the following code: 
$ touch README .md 
$ touch index.html 


$ mkdir js 
$ touch js/script.js 
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TIP 


Note that one of the files you create is a README .md file. To find out why every 
repository should have a README .md file, see Chapter 10. 


After running these commands, you have three files: 


>> README .md 
>> index.html 


>» script.js 


script. js is in a subdirectory named js. You guessed it. — you’re making a 
simple website! 


You can flesh out the README. md file first. In this example, we use Atom to open 
and edit the files in the current directory. (If you need any guidance setting up 
Atom, see Chapter 2.) 


If you prefer, you can easily use another editor, such as Visual Studio Code, to edit 
the file by replacing atom with code in the following example: 


$ atom . 


You can add some simple Markdown text to the README .md document. Markdown 
is language that offers a simple way to format and style your text. You can check 
out a guide on Markdown on the GitHub guides https: //guides.github.com/ 
features/master ing—markdown. 


Open theREADME .md in the editor by clicking in in the file tree in Atom. Then add 
some Markdown relevant to your project. In this example, add the following text: 


# The Best Example Ever 
Which will be a part of the best commit ever. 
Then add the following code to index.html. 


<!doctype html> 
<html lang="en"> 
<head> 
<meta charset="utf-8"> 
<title>It is the cod3z</title> 
<script src="js/script. js"></script> 
</head> 
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REMEMBER 


FIGURE 7-1: 

An alert 

message from 
our running code. 


<body> 

<h1>The Best Cod3z!</h1> 
</body> 
</html> 


This HTML file references scripts.js. Open script.js in Atom and add the 
following code. 


document .addEventListener( 
"DOMContentLoaded", 
function(event) { 
alert('The page is loaded and the script ran!') 
} 
Ne 


Make sure to save your changes to each file. Now test the code by opening index. 
html in your browser from the terminal. 


$ open index.html 


The page loads in your default browser, and the alert message, shown in Figure 7-1, 
appears. 





This page says 


The page is loaded and the script ran! 











Creating a Commit 


This section assumes you have code that you’ve changed on your local computer 
and that the code is in a working state. If you need an example of working code, 
see the previous section in this chapter to get to this state. 


After you have running code, you can commit it to the repository. To create a com- 
mit is a two-step process: 


1. Stage the changes you want to commit. 


2. Create the commit with a commit message. 
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TIP 


Staging changes 


Staging changes can be confusing to the Git beginner. In concept, it’s similar to a 
staging environment for a website. Staging changes is an intermediate place 
where you can see the changes you’re about to commit before you commit them. 


Why would you want to stage changes before committing them? In Git, a commit 
should contain a group of related changes. In fact, Git encourages this setup. 


Suppose that you’ve been working for a few hours and now have a large set of 
unrelated changes that aren’t committed to the Git repository. 


You may be tempted to just commit everything with some generic commit 
message like “A bunch of changes.” In fact, an XKCD commit makes light of this 
phenomena at https: //xkcd.com/1296. 


Committing a bunch of unrelated changes is generally a bad idea. The commit his- 
tory of a repository tells the story of how a project changes over time. Each com- 
mit should represent a distinct cohesive set of changes. This approach to commits 
isn’t just about being fastidious and organized. Having a clean Git history has 
concrete benefits. 


One benefit of a clean Git history is that a command like git bisect is way more 
useful when each commit is a logical unit of work. The git bisect command is 
an advanced command, and full coverage of what it does is beyond the scope of 
this book. In short, though, git bisect provides a way to conduct a binary search 
through your Git history in order to find the specific commit that introduces a 
particular behavior, such as a bug. If every commit contains a large group of unre- 
lated changes, finding the specific commit that introduces a bug isn’t as useful as 
it would be if every commit contains a single logical unit of change. 


In the example for this chapter, we can probably stand to create two commits: 


>> One that just contains the README . md file. 


>> Another that contains the index.html and script. js files. 


Because the index.html] file references the script. js file, checking in one with- 
out the other doesn’t make sense at this point. 


Start by staging the README . md file: 


$ git add README .md 
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TIP 


The README . md file is added to the Git index. The Git index is the staging area for 
creating commits to the repository. You can check the status of the repository to 
see that the file has been added to the index: 


$ git status 
On branch master 


No commits yet 


Changes to be committed: 
(use "git rm --cached <file>..." to unstage) 


new file: README .md 


Untracked files: 


(use "git add <file>..." to include in what will be committed) 
index.html 
js/ 


As you can see, the README .md file is staged for commit. Meanwhile, the index. 
html and js/ directory aren’t yet tracked by this repository. 


Why isn’t script. js listed in the untracked files section? Git is taking a shortcut 
here. It notices that no files within the js directory are tracked, so it can simply 
list the directory rather than list every file in the directory. In a larger code base, 
you’ll be glad Git isn’t listing every file in every subdirectory. 


Committing a file 


After you stage changes (see preceding section), you can create a commit. In this 
example, we use the -m flag with the git commit command to specify a short 
commit message. The following commands demonstrate how to create a commit 
and specify the commit message in one step: 


$ git commit -m "Add a descriptive README file" 

[master (root-commit) 8436866] Add a descriptive README file 
4 file changed, 3 insertions(+), © deletions(-) 

create mode 100644 README .md 


The file is committed. If you run the git status command again, you see that you 
still have untracked files. The git commit command commits only the changes 
that are staged. 
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TIP 


TIP 


Committing multiple file: 


After you commit the first file, you’re ready to stage the rest of the files for a 
commit. 


$ git add -A 

$ git status 

On branch master 
Changes to be committed: 


(use "git reset HEAD <file>..." to unstage) 
new file: index.html 
new file: js/scripts. js 


The -A flag indicates that you want to add all changes in the working directory to 
the Git index. When you run the git status command, you can see that you’ve 
staged two files. 


When the js directory is untracked, git status lists only the js directory and 
none of the files in the directory. Now that you’re trying to stage the js directory, 
Git lists the file in the js directory. Why the discrepancy? Git doesn’t actually 
track directories. It tracks only files. Therefore, when you add a directory to a Git 
repository, it needs to add each file to the index. 


Sometimes you need to write a more detailed commit message. In this example, 
we don’t specify a commit message when we run the commit command because 
we plan to write a more detailed commit message: 
$ git commit 

If you don’t specify a commit message using the -m flag, Git launches an editor 
to create a commit message. If you haven’t configured an editor with Git, it uses 
the system default editor, typically VI or VIM. 

There are legions of jokes about how difficult it is to exit VIM, so we won’t rehash 
them all here. We’ll simply take a moment of silence in remembrance for our 


friends still stuck in the VIM editor. 


For the record, to exit VIM, press the ESC key to exit the edit mode and type : wq to 
exit and save or :q! to exit without saving. 


To change the default editor to something like Atom, run the following command 
in the terminal: 


gitconfig --global core.editor "atom-—-wait" 
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The editor opens a temporary file named COMMIT_EDITMSG, which contains some 
instructions that are commented out: 
TIP 
# Please enter the commit message for your changes. Lines 
starting 
# with '#' will be ignored, and an empty message aborts the 
commit. 


+ 

# On branch master 

# 

# Initial commit 

+ 

# Changes to be committed: 
# new file: README . md 
# 

# Untracked files: 

# index.html 

# js/ 

# 


You will enter your commit message in the file that gets opened. You can write 
your message before all the comments or simply replace everything in the file 
with your own commit message. 

In this case, we replace everything in that file with 


Add index.html and script. js 


This adds index.html to the project. This file is the 
default page when visiting the website. 


This file references js/script.js, which is also added 
in this commit. 


After you save the commit message and close the file or editor, Git creates a com- 
mit with the message you wrote. 


Writing a Good Commit Message 


What should you write in a commit message? What makes a good commit message? 
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REMEMBER 


A Git commit should contain a logical and cohesive change or set of changes. The 
message should describe that change in clear terms so that anyone who reads the 
message later understands what changed in the commit. 


The audience for the commit message are current and future collaborators on the 
project. Those collaborators may include yourself in the future. Someday you may 
be tracking down a bug and want to understand why you made some change. 
You’ll thank past-you for writing a well-written commit message that answers 
that question. So write clear commit messages and be nice to future-you. 


If you find that you have trouble describing a commit, it may be that the commit 
contains too many changes. In writing code, we often note that well written func- 
tions do one thing and do it well. Similarly, a commit should represent one change 
to the system. The commit message describes the change and why it’s being made. 


A good commit message should also follow a specific structure. In general, a com- 
mit message has two parts: 


>> The summary should be short (50 characters or less) and in the imperative 
present tense. For example, instead of writing “| added a method to 
Frobnicate widgets,” write “Add method that Frobnicates widgets.” 


>> The description provides detailed explanatory text, if needed. Not every 
change requires explanatory text. For example, if you rename a function, a 
commit message with just a summary of “Rename Frobnicate to Bublecate” 
may suffice. You should wrap the description text at 72 characters. This 
ensures it looks good when displayed in the terminal as part of the output 
from the git log command. 


By convention, a new line character separates the summary from the description. 


Here’s an example commit message written by one of the authors in an open 
source project https: //git.io/fhZ5a: 


Avoid potential race condition 
In theory, if "ClearFormCache" is called after we 
check ~contains~ but before we execute the `return` 


line, we could get an exception here. 


If we're concerned about performance here, we could 
consider switching to the ConcurrentDictionary. 


CHAPTER 7 Writing and Committing Code 121 


There’re a few conventions you can use within a Git commit message that Git will 
ignore, but GitHub will recognize. For example, you can specify that a commit 
resolves a specific issue with something like “fixes #123” where 123 is the issue 
number. When a commit with this pattern is pushed to GitHub, the issue number 
is linked to the issue. And when the branch that contains that commit is merged 
into the default branch of the repository (typically master), GitHub closes the 
referenced issue. That’s pretty handy! 


You can also use emojis in a commit message. For example, one pattern some 
teams use is to indicate that a commit contains only cosmetic changes by prefac- 
ing it with :art:. When that commit is rendered on GitHub.com, GitHub renders 
TIP the emoji. You can see this in action in Figure 7-2 which shows a list of commits 
from the GitHub for Visual Studio open source project https: //git.io/fhnDu. 





Commits on Oct 27, 2015 


@ Remove redundant parenthesis = & fa6lall <?) 


@ Haacked committed on Oct 27, 2015 v 


Document undocumented method arguments & 
@ Haacked committed on Oct 27, 2015 v 


a2c6743 > 


FIGURE 7-2: se 
, , Nitpicky code cleanup = 
A list of commit f Haacked committed on Oct 27, 2015 
messages, some 
with emojis in the 
summary. 


pı ®  316a6cı <> 


È. Remove unused property -- e stt2ui3 o 
f Haacked committed on Oct 27, 2015 











Committing Code with GitHub Desktop 


Even though committing from the terminal is pretty straightforward, many peo- 
ple prefer to use a GUI application to commit code. Using a GU has a few 
benefits: 


>> A GUI can provide guidance on conventions with commit messages, such as 
keeping the summary to 50 characters and separating it from the description 
by new lines. A GUI can simply present two fields: summary and description. 


>» A GUI can provide support for GitHub specific conventions, such as the one 
where you can specify that a commit resolves an issue. 


GitHub Desktop (which we refer to as Desktop for short) is a GUI created by GitHub 
that is great for committing code. 
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Tracking a repository in Desktop 


Choose a repository that you have never opened in Desktop, but that you have 
locally on your computer. (See Chapter 2 if you haven’t worked with Desktop yet.) 
If you need an example, use the best-example repository that you can create in 
the section “Creating a Repository,” earlier in this chapter. When you launch 
Desktop, the best-examp1le repository isn’t listed in the list of repositories. Desk- 
top doesn’t scan your computer for Git repositories to manage. Instead, you have 
to tell Desktop about each repository you want to manage. 


As expected, if you use Desktop to clone or create the repository, it’s already 
tracking it. But sometimes you have a repository that you cloned or created out- 
side of Desktop — for example, we created best-example using the terminal. Now 
you need to tell Desktop to track the repository you have chosen. Fortunately, this 
task is easy from the terminal. 


The Desktop command line tool allows you to launch Desktop from your terminal, 
which allows you to easily integrate Desktop as much or as little as you want into 
your existing terminal-based Git workflow. 


On Windows, you don’t need to install the command line tool; it’s done automati- 
cally. On the Mac, you have to take a separate step. 


To install the command line tool on a Mac: 
1. Make sure Desktop is the active application and then, in the application 


menu bar, choose GitHub Desktop © Install Command Line Tool. 


2. From the terminal, make sure that you're in the repository you want 
Desktop to track. 


For this example, we are in the best-examp1le. 


3. Runthe following command: 
$ github . 


The . inthe command represents the current directory. It could, instead, be a 
fully qualified path to a directory. 


GitHub Desktop launches (if it's not already running) and opens the specified 
directory. Because the current directory is already a Git repository, Desktop 
adds it to the list of repositories that it tracks. It then sets this repository as the 
current repository so that you can browse the repository's history, switch 
branches, and create commits, as shown in Figure 7-3. 
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FIGURE 7-3: 
GitHub Desktop 
opened to the 
best-example 
repository. 


TIP 


[g Current Repository 


v Current Branch ~ & Publish repository 








best-example ” master Publish this repository to GitHub 
Changes History Add a descriptive README file 

17 No Branches to Compare E Phil Haack committed -O-b692062 (Ñ) 1 changed file 

Add index.html and script.js README.md + ee eene 











QB Phil Haack committed just now 1| +# The Best Example Ever 


2\+ 


Add a descriptive README file 3 +Which will be a part of the best commit ever. 
Phil Haack committed 2 hours ago 











If the current directory wasn’t a repository, Desktop prompts you to create a Git 
repository in that directory. How convenient! 


Publishing a repository in Desktop 


To experience the full power of Desktop’s integration with GitHub, you need to 
publish this repository to GitHub: 
1. Clicking the Publish repository button. 
A dialog box to publish the repository appears (see Figure 7-4). 
2. Fill in the details and click the Publish Repository button. 
The repository is created on your GitHub.com account. 


Desktop provides a keyboard shortcut to open the browser to the repository: %8 + 
Shift + G (Ctrl+Shift+G on Windows). 


If you want, you can create a few issues in the repository. (see Chapter 3 to find 
out how to create issues.) For this example, we create five issues: 


>> Provide more details on the README. 


>> Mention in the README that this is a collaborative efforts. 
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>> Add a contribution section to README. 
>» Do not use an alert message. 


>> Set up website alerts. 





Publish Repository x 


GitHub.com Enterprise 





Name 


best-example 


Description 


An example for GitHub for Dummies 
(_)Keep this code private 


Organization 
FIGURE 7-4: 
The Publish 
dialog box used 


to publish a : : 
repository to Cancel Publish Repository 


GitHub.com. 


None 7 








You can also see these issues on our repo at https: //github.com/FakeHaacked/ 
best-example/issues. 


Committing in Desktop 


Desktop is used only for Git operations. To edit the files in the repository, you still 
need to use your editor of choice. 


Make some changes so you have something to commit. In the example for this 
chapter, you can make some changes to index.html shown in bold. 


<!doctype html> 
<html lang="en"> 
<head> 
<meta charset="utf-8"> 
<title>The Best Example</title> 
<script src="js/script.js"></script> 
</head> 
<body> 
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<hi>The Best Cod3z!</h1> 
<div id="message"></div> 
</body> 
</html> 


Update script.js to populate the new DIV element, like civilized people would, 
rather than pop up an alert message. Changes are in bold: 


document .addEventListener( 
"DOMContentLoaded", 
function(event) { 
var message = document.getElementById( 'message' ) 
message.innerText = 'The script ran!' 
} 
Ni 


Switch back to Desktop and click the Changes tab, shown in Figure 7-5. 


Changes tab 














p Current Repository ~ jp Current Branch ~ a Pushorigin 
best-example / master Last fetched a minute ago 
Changes 2 History index.html {e) 
2 changed files @@ -2,10 +2,11 @ 
2 2 <html lang="en"> 
index.html . si aab 
js/script.js (=) 4 4 <meta charset="utf-8"> 





- <title>It is the cod3z</title> 
+ <title>The Best Example</title> 


6 6 <script src="js/script.js"></script> 

7 7 </head> 

8 8 <body> 

9 9 <hl>The Best Cod3z!</h1> 
EEE] + <div id="message"></div> 

10 11 </body> 

11 12 </html> 


g Summary (required) 


Description 


FIGURE 7-5: 

The Changes 

View showing the | Committomaster | 
uncommitted Committed 11 minutes ago 

cha nges. Add index.html and script.js 


a+ 


Undo 











The left pane lists the set of changed files. If you select a file, you can see the spe- 
cific changes to that file in the right pane, which is called the diff view. 
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WARNING 


You can commit all the changes as a single commit, but sometimes you will have 
unrelated changes. In this example, we have two unrelated changes: 


>> The change to the title in index.html 


>> The message changes to both index.html andscript. js 


Each of these changes should be in their own commit. How do we do that when 
index.html contains two unrelated changes? Fortunately, Desktop provides a 
nice way to commit a portion of the changes in a file. This process is known as a 
partial commit: 


1. Deselect all changes. 


In the left pane, uncheck the check box next to the label2 changed files to 
deselect all changes. 


2. Select index.html in the left pane. 
Click the filename in the left pane to display the changes for index.html. 
3. Select the title changes. 


In the diff view, click the line numbers in the gutter to select the changes you 
want to keep. To select a whole code block, click the thin line just to the right of 
the line number. Select the code block next to line 5 by clicking on the thin line 
next to line 5. After you select the code block, both lines labeled line 5 should 
be selected (selected lines show up as blue), as shown in Figure 7-6. 


You may be confused about why two lines are labeled 5 in the diff view. The 
numbers on the left represent what the file was originally named before you 
made the changes. The lines on the right represent the lines of the changed 
lines. Because we changed line 5, it's listed twice. Line 10 is a new line that 
didn't exist before, so it is listed only on the right. 


4. With those lines selected, enter a commit message and then click the 
Commit to master button. 


As you can see in the bottom left portion of Figure 7-6, Desktop provides two 
fields for commit messages. Go ahead and enter “Change the title” into the 
summary and click the Commit to master button. 


Notice that the diff view updates to have the change only on line 10 (see 


Figure 7-7). That's because we committed the change on line 5. 


If you’re following the example in this chapter, make sure all the remaining 
changes are selected by clicking the check box next to the label 2 changed files 
until the check box is selected. 


CHAPTER 7 Writing and Committing Code 127 


FIGURE 7-6: 

The diff view 
with one change 
selected. 


FIGURE 7-7: 

The Changes tab 
after a partial 
commit. 
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Current Branch 


t Push origin 











[g Current Repository oy: 
wal ae, 1+ 
best-example * master Last fetched 18 minutes ago 
Changes 2 History index.html i} 
Ss 2 changed files @@ -2,10 +2,11 @@ 
2 2 <html Lang="en"> 
is/script.js ig] 4 4 <meta charset="utf-8"> 
- <title>It is the cod3z</title> 
+ <title>The Best Example</title> 
6 6 <script src="js/script.js"></script> 
7 7 </head> 
8 8 <body> 
9 9 <hl>The Best Cod3z!</h1> 
10} + <div id="message"></div> 
10 11 </body> 
11 12 </html> 
wi Update index.htm! 
Description 
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Commit to ter 
Committed 29 minutes ago TA 
Add index.html and script.js 
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Changes 2 History index.html O] 
e 2 changed files @@ -7,5 +7,6 @@ 
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a Update index.html 


Description 


1+ 





Committed just now 


Und 
Change the title Hoe 
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Using GitHub Conventions in 
Commit Messages 


FIGURE 7-8: 
The emoji picker 
listing emojis. 


You can enhance your commit messages with GitHub-specific features, such as 
emojis, issue references, and coauthor credits. 


Emojis 
Emojis are little images or icons that convey an emotion or concept. Widely used 


on GitHub.com, emojis can bring a bit of levity and whimsy to an otherwise seri- 
ous occupation. 


In the commit summary box, you can initiate the emoji picker by typing the : 
character. If you keep typing, you can list all emojis that start with the letters you 
type. For example, Figure 7-8 lists all emojis that start with ar as the result of 
typing :ar. 





$ :art: 


:aries: 


Descr! 


it 


Commit to master 


Committed 17 minutes ago 


Change the title apco 











You can select the one you want with the arrow keys and then press Tab to com- 
plete it. Desktop then fills in the full text of the emoji, which in this case is :art:. 


Issue references 


GitHub also lets you reference an issue in a commit message with the format #123 
where 123 is the issue number. Desktop has support for looking up an issue when 
writing a commit message. To try this out, create an issue ahead of time so that 
you can reference the issue in a commit message. As an example, we created an 
issue that describes the need to replace the alert message with a better approach. 
We reference that issue in this commit message. 
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A list of issues 
with the word 
“alert” in them. 
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To reference an issue in a commit message: 


1. Inthe commit description field, type Fixes #. 


A few recent issues appear. If you don't see the issue you want to reference 
and you don't remember the issue number, You can start typing a word that's 
in the issue that you remember. For example, when we type #alert a couple of 


TIP issues pop up (see Figure 7-9). 





g :art: Replace alert with something 


Fixes #alert 


#5 Set up website alerts 


#4 Do not use an alert messaj 





FIGURE 7-9: Commit to master 


Committed 20 minutes ago 


Und 
Change the title leas 








2. Select the issue you want to reference and press Tab. 


In this example, we select issue 4. Desktop replaces 


Giving credit to coauthors 














alert with #4. 


Git doesn’t support multiple authors directly. However, the Git community cre- 
ated a convention for specifying multiple coauthors in a commit that is now sup- 


ported by GitHub. 


To give credit to coauthors: 


1. With the Desktop open, in the commit box with the Description label, 
click the little icon with a person and a plus sign in the bottom left 


corner. 


Desktop adds a textbox to enter a coauthor’s GitHub username. 


2. Click the @ symbol to see a list of potential users, as shown in Figure 7-10. 


GitHub lists only users who have access to the repository — for example, 
collaborators and org members (if the repository belongs to an organization). 
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TIP 


FIGURE 7-10: 
A list of potential 
coauthors. 


FIGURE 7-11: 
The newly 
created commit. 


Just like the issue selector, you can also search by first name, last name, or 


username by appending a bit after the @. For example, if | only remember y 


coauthor's last name, | could type @guth to find my coauthor. Press Tab, 


and Desktop replaces whatever you typed so far with the selected user’s full 


username. 





Fixes #4 


at 


Committed 391 
Change the title 





a :art: Replace alert with something 


haacked Phil Haack 


sarah-wecan Sarah Guthals 


fakehaack... This is not the real Haac... 











3. To create the commit, click the Commit to master button. 


To see your commit, click the History tab and click the you just created (see 


Figure 7-11). 


fm] Current Repository 
= best-example 
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@ Replace alert with something better 


aș Push origin 
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Și Phil Haack and Sarah Guthals committed -© 8699853 [#))2 changed files 
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Co-Authored-By: Sarah Guthals <sarah-wecanęusers.noreply. github. com> 


index.html 
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</head> 
<body> 

<h1>The Best Cod3z!</h1> 
+ <div id="message"></div> 
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</html> 











CHAPTER 7 Writing and Committing Code 


131 


You can see in the commit message in the right pane that Sarah’s username was 
replaced by the line 


Co-Authored-By: Sarah Guthals <sarah—-wecan@users.noreply.github.com> 


That’s the actual convention for specifying coauthors in Git commit messages. By 
using Desktop, you don’t have to remember the exact format. You can just specify 


a username and let Desktop handle the rest. 
REMEMBER 


Committing Code from Your Editor 


Many editors have built-in support for committing code. Built-in support allows 
you commit code without having to switch to another application. The downside 
is that different editors have different levels of support for the various conven- 
tions you can use in a commit message. 


But for quick and dirty commits, built-in support is very useful. Covering how 
every editor supports Git commits is out of the scope of this book, but you can see 
this in action with Atom in Chapter 5. For other editors, refer to their specific 
documentation. 


FOR MORE READING 


A lot of great guidance is out there for writing good commits. For example, the Git 
documentation at https: //git-scm.com/book/en/v2/Distr ibuted-Git- 
Contributing-to-a-—Pro ject has a section on contributing to a project and 
includes some Commit Guidelines. 


I'm also a fan of a blog post by Chris Beams entitled “How to Write a Git Commit 
Message,” which you can read athttps: //chris.beams.io/posts/git-commit/ 
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IN THIS CHAPTER 


» Creating a pull request 





» Writing a great pull request 
» Reviewing a pull request 


» Exploring pull request workflows 


Chapter 8 


Working with Pull 
Requests 


n Chapter 7, we note that a commit is the smallest unit of work with Git. On 
GitHub, the pull request is the main unit of work. 


In this chapter, we explain exactly what a pull request is and how it pushes code 
to GitHub. We also describe the processes for opening, writing, and reviewing a 
pull request. 


Understanding a Pull Request 


The name pull request is confusing to some folks. “What exactly am I requesting 
to be pulled?” Good question. A pull request is a request to the maintainer of a 
repository to pull in some code. 


When you write some code that you want to contribute to a repository, you create 
and submit a pull request. Your code contains some proposed changes to the target 
repository. A pull request is your way of offering these changes to the maintainer 
of the repository. It gives the repository maintainers an opportunity to review the 
changes and either accept them, reject them, or ask for more changes to be made. 
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Pushing Code to GitHub 
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TIP 


TIP 


To push code to GitHub, you need a repository. Open the repository of your choice. 
If you don’t have a repository yet, Chapter 7 walks through creating a repository 
that you can use. 


If you’d like to follow along with our example but you haven’t completed the 
steps in Chapter 7, fork the repository https: //github.com/FakeHaacked/best-— 
example and then clone your fork to your local machine. If that last instruction 
sounds like gobbledygook to you, you may want to review Chapter 6, which covers 
forking and cloning. 


The first thing to do is create a new branch. Creating a new branch before writing 
new code is standard operating procedure with Git. I have a confession to make. 
We neglect to mention that in the example in Chapter 7. The example directs you 
to commit code directly to the master branch. That was a shortcut we suggested 
to keep things simple. 


In this chapter, you’ll do things the right way and work in a new branch. There’s 
an important reason for this. A pull request doesn’t consist of an arbitrary set of 
changes or commits. A pull request is always associated with a branch. In other 
words, a pull request is a request to merge one branch into another. 


While it’s true that a pull request can target any branch (except itself), the most 
common scenario is to target the main branch of a repository, typically named 
master. 


This relationship between pull requests and branches is why you should create a 
new branch when starting new work. We name the branch new-work for this 
example, but feel free to name it whatever you want by replacing new-work with 
your own branch name in the following command: 


$ git checkout -b new-work 


Now that we have a branch, we need to create a commit in that branch. For this 
example, the specific contents of the commit are not important. You can choose 
any file and make some edits to the file, such as adding some text to the end. Or if 
you’re following along with the repository we created in Chapter 7, manually edit 
the README .md file manually or run the following command to append some text 
to end of the file: 








$ echo "\n## Installation" >> README.md 
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Now that you have a file with some changes, commit those changes. You can use 
the following command, for example, to commit all your changes. The commit 
message is not important here. The important thing is to have a commit in a 
branch to work with that is not in the master branch. 


$ git add -A 
$ git commit -m "Add text to the README" 


Now push this new branch to GitHub.com (replace new-work with your branch 
name): 


$ git push -u origin new-work 


The git push command tells Git to push local commits to a remote repository. 
The -u flag specifies where to push it — in this case, to a branch also named 
new-work on the remote named origin. 


The -u flag is only needed the first time you push a new branch to the server. From 
that point on, the new-work branch on your local machine is associated with the 
new-work branch on GitHub.com and any subsequent pushes to that branch do not 
need the flag. 


Opening a Pull Request 


Before you can open a pull request, your GitHub.com repository must have at least 
one branch other than the default branch. If you follow the steps in the earlier 
section “Pushing Code to GitHub,” you have a branch that is not yet merged into 
master. In our case, the branch is named new-work branch, but you may have 
named yours something else. Visit the repository on GitHub.com to open a pull 
request. 


When you visit the repository on GitHub.com, you see a new message in the 
section labeled Your recently pushed branches, as shown in Figure 8-1. 


Click the Compare & pull request button to navigate to the Open a pull request 
page, as shown in Figure 8-2. The target branch (the branch you want to pull your 
changes into) is the default branch for the repo. Your branch is listed next to the 
target branch, and a status of whether your branch can be merged into the target 
branch is next to that. The pull request title is the same as the most recent commit 
message — in this example Add text to the README — and your description is 
blank. Figure 8-2 shows an example description. 
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FIGURE 8-1: 
Repository home 
page with 
recently pushed 
branches listed. 


FIGURE 8-2: 
The Open a pull 
request page. 
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2. It is short. 
3. It is sweet. 


This is the best pull request to the best example ever because: 


This PR adds some text to the "README, md’ file as suggested by @sarah-wecan. :sparkles: 
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Pull request title 
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Pull request description 





Projects and Milestones 





Create button Labels 








TIP 


You can change the default branch by choosing Settings = Branches section of your 
repository. 


GIT ALIAS FOR OPENING GITHUB.COM 
FROM THE TERMINAL 


Often when working with a repository in the terminal, you need to jump to the reposi- 
tory on GitHub.com. | have an alias just for this purpose. Chapter 6 covers aliases in 
more details and how to add them. You can run the following in the terminal to add a 
new git browse alias. 


$ git config --global alias.browse '!open ~git config remote.origin.url~' 


To use the alias, just run the following in the terminal from within your repository 
directory. 


$ git browse 


This code launches your default browser and navigates to your repository’s origin URL. 
This alias assumes you're using https for your git remotes and not SSH. 


GIT ALIAS FOR OPENING THE BRANCH 
COMPARE WEB PAGE 


If, for some reason, the branch for which you want to create a pull request isn’t listed in 
the recently pushed branches section, you can navigate to the Compare page for your 
branch, which has the format https: //gitub.com/{owner}/{repo}/compare/ 
{BRANCH}. As luck would have it, | have an alias for that: 


$ git config --global alias.pr '!f(){ URL=$(git config 
remote.origin.url); open ${URL%.git}/compare/$(git 
rev-parse --abbrev-ref HEAD); }; f' 

$ git pr 


Just as with the git browse alias earlier in the sidebar “Git Alias for opening GitHub.com 


from the terminal”, this alias assumes you use HTTPS URLs for your remotes and 
not SSH. 
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FIGURE 8-3: 


List of potential 
reviewers with 
two reviewers 
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selected. 


Describing the pull request 


From the Open a pull request page, you can enter a summary and description. 
Chapter 7 covers some GitHub conventions for commit messages. Most of those 
conventions are also supported in a pull request — for example, mentioning 
people using the @USERNAME format. In Figure 8-2, I mention @sarah-wecan. 
When I create the pull request, @sarah-wecan receives a notification. 


You can reference issues and other pull requests using the # ISSUEID format. And, 
of course, you can add emojis, such as :sparkles:. 


In this section, we cover what to write here in more detail. There’s a lot that goes 
into a good pull request. 


Adding reviewers 


To the right of the pull request summary and description fields is a set of options 
for the pull request. 


The first one, Reviewers, lets you specify one or more people that you want to 
review your pull request. To add reviewers: 
1. Click the gear to see a list of people you can mention. 


For repositories with a large number of users, you can start typing to filter the 
set of users. 


2. Click each user to add them to the list of reviewers. 


When you add a reviewer, they're immediately notified when you finish 
creating the pull request. Figure 8-3 shows the reviewers list with two 
reviewers selected. 





Reviewers [o] 


( Request a review 


v & FakeHaacked This is not the real 
Haacked 


v EÑ sarah-wecan Sarah Guthals 


Projects 


None yet 
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TIP 


Specifying assignees 


The next option after Reviewers is an option to specify assignees. An assignee is 
the person who should take action on the pull request. Often, a pull request rep- 
resents a work in progress and not the final result of some work. If more work 
needs to be done on a pull request, you’d assign the pull request to the person that 
should do the work. 


To specify assignees: 


1. Click the gear to see a list of assignees. 


The assignee dialog box works just like the reviewers dialog box, described in 
the preceding section. It allows you to select one or more assignees. 


2. Click each user to add them to the list of reviewers. 
In most cases, it’s best to just assign one person who will be responsible for the 


next step. Assigning one person reduces the chances that multiple assignees all 
think the other assignees are responsible for the work. 


Specifying labels 


Chapter 3 introduces labels on issues as a way to figure out what to work on next. 
Labels work the same way for pull requests. They provide convenient grouping 
and context to help you decide what to work on next or what to review next. 


The set of labels you can use on issues and pull requests are the same, but some 
labels make more sense for issues than pull requests and vice versa. For example, 
many repositories have a “ready for review” label specifically for pull requests. 


Specifying projects and milestones 


The last two options allow you to specify the project board and milestone that this 
pull request belongs to. Chapter 3 covers projects, and Chapter 11 covers 
milestones. 


Creating the pull request 


After you have the pull request written and specified all the pull request options, 
click the Create pull request button to save all your work and create the pull 
request. Figure 8-4 shows a pull request I created on my repository. 
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FIGURE 8-4: 
A created pull 
request. 
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This PR adds some text to the README.md file as suggested by @sarah-wecan. `+ 


FA sarah-wecan 


Assignees 


g Haackea 


Labels 


enhancement 


- 


FakeHaacked / best-example Qwatchy 1 Star 0 YFork 0 
Code Issues 5 T) Pull requests 1 Projects 0 Wiki Insights 
Add text to README eal 
Haacked wants to merge 1 commit into master from new-work 
Conversation 0 Commits 1 E Checks 0 (Files changed 1 +2 -0mm 
g Haacked commented 10 minutes ago « edited ~ Collaborator Reviewers 
[OY FakeHaacked . 


+- E 


ready for review 











Writing a Great Pull Request 


WARNING 


140 


Writing a great pull request is a bit of an art. For an open source project, much of 
the project’s communication with people occurs within pull requests. 


If you’re contributing to a project, your pull request is your chance to make a 
strong case for why your code should be pulled into the main branch. Make sure 
to put your best foot forward. 


Knowing your audience 


Before you write a single word, understanding your audience is helpful so that you 
can focus your words on what is most useful. A pull request may serve many audi- 
ences. Keeping all of your audiences in mind is important, but your primary focus 
is on the folks who will review and make a decision on whether your pull request 
will be merged. You want to make their lives easier as they tend to be very busy. 


Even though the project maintainers are your primary audience, you should never 
forget that many others will read the pull request. For an open source project, that 
audience may be the entire world. So keep your language respectful, friendly, and 
inclusive. 


It’s pretty common to have someone write a pull request in a fit of anger and later 
regret the words they use. So if you happen to be rage coding, take a moment to 
cool down and gather your thoughts before creating the pull request. 
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TIP 


Making the purpose clear 


Make sure to be concise and informative. For example, the summary should make 
the purpose of the pull request clear. The summary is the only part shown on the 
page that lists pull requests. It needs to be scannable. 


Here are some examples of good pull request summaries: 
>> Adds the About page to the website 


>» Minimize boilerplate setup code for JavaScript libraries 


>> Extract and isolate error handling from GitStore internals 
Here are some bad examples taken from my own repositories. 


>> Teams are forever 
>> Typo 
>» Small changes 
The description should provide a bit more explanation about the purpose of the 


pull request. Don’t write a book, but do make it clear what the pull request 
attempts to accomplish. 


Keeping it focused 
Much like a commit, a pull request should not contain a bunch of unrelated 


changes. A pull request may consist of multiple commits, but they should all be 
related to the task at hand. 


You can often tell that a pull request is doing too much when writing a concise 
description of what the pull request accomplishes is difficult. 


Even if the pull request is focused on a single major change, keep the pull request 
to a manageable size. Reviewing a very large pull request is difficult. 


If the pull request addresses a very large task, break down the task into smaller 
steps and submit pull requests for each step. 
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Explaining the why 


The previous suggestion, “Keeping it focused,” focuses on what the pull request 
does. You also need to explain why you’re taking on this work. The pull request 
description is an opportunity to provide links to other documents that provide 
more context. You can’t assume everyone will be familiar with the history. 


If you have a lot of context to share, you can provide a brief summary followed by 
more details within a <details> tag. For example, if you add a pull request com- 
ment with the following text: 


The reason we're embarking on this work is due to compliance reasons. 

<details> 

## More Details 

I don't want to bore everyone with all the nitty gritty details, but for those 
who are interested, keep on reading... 

</details> 


GitHub displays the details section collapsed by default, as shown in Figure 8-5. 

















2 Haacked commented 14 seconds ago Collaborator 
The reason we're embarking on this work is duet to compliance reasons. 
FIGURE 8-5: 
Details section > Details 
collapsed. 
Click the details label to expand the details section, as shown in Figure 8-6. 
a Haacked commented 14 seconds ago Collaborator 
The reason we're embarking on this work is duet to compliance reasons. 
v Details 
FIGURE 8-6: ## More Details | don't want to bore everyone with all the nitty gritty details, but foro those whoo are 
Details section interested, keep on reading... 
expanded. 











A picture is worth a thousand words 


GitHub supports adding images to a pull request description by dragging and 
dropping an image. When you drag and then drop the image on the text field, 
GitHub uploads the image and replaces it with the markdown for rendering an 
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FIGURE 8-7: 
Uploading an 
image to a pull 
request. 


TIP 


image. Figure 8-7 shows an upload in progress after I dragged an image into a pull 
request comment field. 


f . 
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CD Styling with Markdown is supported Close and comment 














Visit https: //github.com/FakeHaacked/best-example/pul1/6#issuecomment— 
454927796 to see this comment. It’s very meta as it’s a screenshot of the same 
repository it’s a comment on. 


If an image is worth a thousand words, an animated gif is worth even more. If you 
can create an animated gif that demonstrates the behavior change introduced by 
the pull request, adding that gif to the pull request is usually very appreciated by 
those who review it. 


Including a call to action 


You need to be very clear about what feedback you want from others on the pull 
request. For example, if the pull request is a work in progress, make that clear 
from the start so that people don’t waste time reviewing a pull request that isn’t 
ready for review. 


To make that clear, follow the conventions of the repository. You can find out the 
conventions by orienting yourself with the repository as described in Chapter 5. 


WRITING A PERFECT PULL REQUEST 


The previous suggestions describe writing a great pull request. It's not comprehensive. 
For more suggestions, check out a blog post on the GitHub blog entitled “How to write 
the perfect pull request” athttps : //blog. github. com/2015-@1-—21 -how-to-wr ite- 
the-per fect-pull-request/. 
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Following the conventions is important so that others know what is expected of 
them with respect to your pull request. 


Reviewing a Pull Request 


REMEMBER 


FIGURE 8-8: 
Message 
requesting your 
review on this 
pull request. 


Pull requests have two parties involved: the person who writes and opens the pull 
request, and the person (or people) who reviews it. In this section, you put your- 
self in the position of a reviewer of a pull request. 


Reviewing a pull request is a very active activity. It takes a lot of focus and atten- 
tion to do it well. It doesn’t serve the folks submitting pull requests if you just take 
a cursory look at it, comment LGTM (Looks Good To Me), and don’t provide qual- 
ity feedback. 


Sometimes, a cursory look is all you have time for. In that case, make it clear what 
you did and didn’t review and suggest that someone else provide a more detailed 
review. 


When someone adds you as a reviewer, you’ll receive a notification about the 
request, typically via email or on your notification bell at the top right of GitHub. 
com. If you visit the pull request, you’ll see a banner message, as shown in 
Figure 8-8. 
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More Details Assignees 

f g Haackea 
This is the best pull request to the best example ever because: 

1. It is descriptive. Labels 

2. Itis short. enhancement 

3. It is sweet. ready for review 
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WARNING 


TIP 


FIGURE 8-9: 
Pull request with 
failed checks. 


Don’t click the Add your review button just yet. That takes you to a dialog box to 
write a write-up of your review. Only do that when you’re ready to complete your 
review. 


Reviewing the Conversation tab 


When you review a pull request, the first thing to do is read through the contents 
of the Conversation tab for the pull request. Make sure that you understand the 
purpose of the pull request and why it’s necessary. 


At the bottom of the conversation is a section that displays the checks that GitHub 
runs against the repository if there are any. If no checks are set up, you see the 
message Continuous integration has not been set up. The status of these 
checks is the next thing you should check. Many repositories will have several 
checks, such as does the code compile, did all the tests pass, and so on. 


If any of these tests fail, you shouldn’t spend any more time reviewing the code. 
The person submitting the pull request can see that their pull request doesn’t pass 
all the checks, and it’s up to them to fix it. 


Even though the person submitting a pull request should be able to see that the 
checks have failed, sometimes they don’t stick around long enough after creating the 
pull request to see that. You may want to add a gentle note that mentions the person 
submitting the pull request and informs them that the checks have failed and he 
should try fixing the problems and push his changes to the pull request branch again. 


Figure 8-9 shows an example from the GitHub Desktop open source project of a 
pull request that fails the continuous integration (CI) builds. 





© Review required Add your review 


At least 1 approving review is required by reviewers with write access. Learn more. 


© All checks have failed Hide all checks 
1 errored and 3 failing checks 

x eS continuous-integration/travis-ci/pr — The Travis CI build could not complete ... Details 

x & Continuous Integration — #20190114.22 failed Details 

x fo] ci/circleci: build — Your tests failed on CircleCI GOMSE Details 

x [9] continuous-integration/appveyor/pr — AppVeyor build failed Details 


(2) Merging is blocked 


Merging can be performed automatically with 1 approving review. 


You're not authorized to merge this pull request. 
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WARNING 


Reviewing the changed files 


Assuming you’re happy with the contents of the Conversation tab and all the 
checks pass, it’s time to get into nitty gritty and review all the file changes. Click 
the Files changed tab to see all the changes in the pull request. 


At this point, you should review the code for things like 


>> Clarity: Is the code easy to read and understand? Could it be made more 
clear? there appropriate comments throughout the code? Obtuse, hard-to- 
understand code becomes a maintenance nightmare down the road. 


>> Correctness: Does the code do what the pull request says it does? Are there 
any glaring bugs? Are there any errors of omission? Are there any tests 
missing? 


>> Security: Related to the previous item, a security review requires a specific 
mindset. Ideally, you work with security experts who can help review the code 
for security. The idea here is to think about all the ways a bad actor could 
attempt to attack the code. There are many frameworks for doing security 
review, such as STRIDE. You should also think about how bad actors can use 
the code to harm other users. Does the code protect users privacy? Does it 
ask for consent to take actions on behalf of users. 


>> Conventions and idioms: Just because code is correct, it doesn’t mean it’s 
necessarily idiomatic. A code review is a good place to teach and learn 
conventions and idioms specific to a project. 


In the last section, we mention conventions. By conventions, we mean common 
approaches to accomplishing a task. For example, if your project has a certain 
approach to querying the database, make sure the code follows that approach. 


One thing to note is we don’t cover code style issues in the list of things to review. 
A code review should not cover nitpicks like whether a curly brace goes on its own 
line or not. An overly pedantic nitpicky code review does not set a friendly and 
collaborative tone. Depending on the context, you can just fix these things your- 
self or better yet, use automated tools, such as a linter or prettifier, to do it. You'll 
save everyone a lot of time and headaches. 


Commenting on code 


When reviewing changed files, you can add comments to specific lines of code to 
indicate a problem with the code, add a suggestion to make it better, or celebrate 
someone’s awesome code writing skills with a :sparkle:. 
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TIP 


FIGURE 8-10: 

Pull Request 
Comment form 
for a line of code. 


Positive and encouraging comments set for a welcoming and collaborative tones. 
Maintainers often forget how daunting it can be to contribute code to a project for 
the first time. Don’t be stingy with the :sparkle: emojis! 


To comment on code: 


1. 


2. 


Hover your mouse over the line of code. 
A blue square with a plus sign appears next to the line number. 


Click the square to reveal a comment form for that specific line of code, 
as shown in Figure 8-10. 


The comment form supports the same things issues and pull requests do, such 
as mentions, Markdown, and, of course, emoji. 


At this point, you can choose to click Add single comment or Start a review. 


Clicking Add single comment immediately adds your comment to the pull 
request and sends out any notifications. This can be useful when making a 
quick one-off comment. In most cases, we recommend against this approach 
as it doesn't lead to well considered and thoughtful code reviews. 











2 mm README. md © Show comments <> B Copy path View| 
@@ -1,3 +1,5 @ 
# The Best Example Ever 
Write Preview ABi €00 =ES ONS 
® Seems a bit _superlative_, no? Will the audience agree with this? 


@sarah-wecan, any thoughts on this? 


Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 








CD Styling with Markdown is supported Cancel Add single comment Start a review 





Which will be a part of the best commit ever. 





3. 


Click Start a review instead to create a review and add the comment as a 
pending comment to the review, as shown in Figure 8-11. 


The pending label indicates that you're the only one who can see the comment 
so far. By starting a review in this manner, you can continue to add (and edit) 
pending comments as you review the code and only publish them when you're 
completely satisfied with the review. 
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Pending 
comment in 
pull request 

review. 


TIP 





2 mum README.md © Show comments <> B Copy path View| 


Q@ -1,3 +1,5 @ 


# The Best Example Ever 


SA FakeHaacked Owner Pending 
& Seems a bit superlative, no? Will the audience agree with this? 


@sarah-wecan, any thoughts on this? 


B] Reply... 





Start a new conversation Finish your review 





The reason we recommend starting a review as opposed to adding single comments 
as you go is a review leads to a more coherent and helpful code review. A common 
occurrence when reviewing code is that something you read later in the review 
makes you realize a comment you made earlier should be updated or even deleted. 
A review lets you make those adjustments before you send anything to the author. 
This option gives you an opportunity to review your review before publishing it. 


Suggesting changes 


Sometimes as you review code, you come across a section of code where you feel 
like it’d be faster to just fix the code than try to explain in words what should be 
fixed. 


Or perhaps you run into a lot of small errors, such as typos, where commenting on 
each one produces more noise than just fixing them. For these situations, GitHub 
supports suggesting a change via a pull request comment that the author can 
apply with a click. 


To suggest a change: 


1. Opening the comment form for the line of code you want to change. 


When you bring up the comment form, you see an icon with a + and - symbol. 
When you hover over the symbol, the tooltip describes the purpose of this 
button (see Figure 8-12). The tooltip also describes a keyboard shortcut you 
can use to suggest a change, CMD +G. 


2. Click the Suggest changes button. 


GitHub adds a suggestion block into the body of your comment with the 
current contents of the line you want to change. 
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FIGURE 8-12: 
Comment form 
with the Suggest 
changes button. 


FIGURE 8-13: 
Comment with a 
suggested change. 


TIP 





+ 


5 + ## Installation a 
Insert a suggestion <cmd-g> 


Write Preview A B i 6 e EES ORAS 





Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 





ED Styling with Markdown is supported Cancel 








3. Change the contents of the block to suggest what the final result 
should be. 


Figure 8-13 shows an example where | suggest a change to add the word 
“Instructions” to the line. 





4 + 
+ ## Installation 


Write Preview MABi «Oo FEET OWNS 





*** suggestion 
## Installation Instructions 






Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


CD Styling with Markdown is supported Cancel Add review comment 














Anything you write outside of the suggestion block in the comment is not included 
in the suggested change. This lets you provide a reason for the suggested change. 
Except for truly simple or self-explanatory suggestions, we recommend always 
providing this extra context. 


After you create a comment with a suggested change, GitHub displays the change 
as a small diff within the comment. If the person viewing the suggestion has 
commit access, they will see an option to commit the suggested change (see 
Figure 8-14). They will also thank you for saving them time! 
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$ 


+ ## Installation 


FakeHaacked 26 seconds ago Owner 


Suggested change [Beta] © Give us feedback 


- ## Installation 


a= 


5 + ## Installation Instructions 








FIGURE 8-14: Commit suggestion v ! 
Comment with a 
suggested 
58 Let's be more explicit about what this section is. 
change. 


Finishing the review 


After you have made all your suggestions, you can finish the review so the author 
receives all your valuable feedback and can start to address it. To finalize the 
review, click the Finish your review button at the bottom of any pending comment 
(refer to Figure 8-11). 


You see a form where you can write your overall summary about the pull request. 
This form is an opportunity to bring up any review comments that are not specific 
to any lines of code. It is also a good opportunity to offer some general praise, 
raise broad concerns, suggest follow-up actions, and so on. 


After you type your comment, check one of the options to indicate your position 
on the pull request. Figure 8-15 shows the comment form with the review options. 





Jump to.. v +2 -0mm Diff settings v Review changes (2] X 


+ 





r Write Preview AA B i C6 <> D sier @ ls) 
pi! | like the direction this is heading. | did not find any glaring errors or omissions. 
p? 


| did add one open question and suggest a change. | wanted to hear your feedback on those 


o! suggestions before | approved the pull request. It's not necessary that you take the suggestions. 
Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


Comment 
Submit general feedback without explicit approval. 


y Approve 
Submit feedback and approve merging these changes. 


f © Request changes 
FIGURE 8-15: Submit feedback that must be addressed before merging. 


Comment with a 
2 pending comments 
suggested 


change. L- 
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If you’re reviewing your own pull request, the only option available is to Comment 
on the pull request. 


TIP 
Your choice may determine whether this pull request can be merged into the 


default branch. Whether your choice blocks a merge depends on how the branch 
protection rules in place for the repository. For example, some repositories may 
require a certain number of approved reviews before the pull request can be 
merged. Go to Settings Branches to manage branch protection rules. 


Reading More About Pull Requests 


Pull requests and code reviews are a very important part of the software develop- 
ment lifecycle. As such, a lot of great advice is out there for doing these things 
well — more advice than we can offer in a single chapter. Here’s some more 
articles to read to help you get the most out of pull requests and code review. 


>> Building an Inclusive Code Review Culture: How you review code is a 
reflection of your overall culture. This article describes an approach that is 
inclusive and collaborative. 


https: //blog.plaid.com/building-an-inclusive-code-review-culture/ 


>> Code Review Like You Mean It: This article is a brief write-up about the 
efficacy of code review along with some tips on how to do them well. 


https: //haacked . com/archive/2013/10/28/code-review-1ike-you-mean-it.aspx/ 


CHAPTER 8 Working with Pull Requests 151 


Manage and 
Contribute to 
Large Projects 


IN THIS PART... 


Find open source software projects (OSS) on 
GitHub.com. 


Discover effective strategies for contributing to OSS. 


Read and understand contributing guidelines for large 
projects. 


Set up a repository so that it’s ready for an OSS project. 


Discover strategies from OSS that are useful for large, 
private projects. 


Create a team on GitHub to better manage your inner- 
source project. 


IN THIS CHAPTER 


» Exploring OSS projects on GitHub 





» Contributing to OSS 


» Contributing guidelines 


Chapter 9 


Exploring and 
Contributing to OSS 


or developers, GitHub is the greatest source of treasure ever created, if you 
know where to look. An open source repository exists for every possible need 
out there. This cornucopia of choice can be overwhelming at first. 


Going beyond just making use of open source software (OSS), contributing to open 
source is a fantastic way to continue your development as a software developer. It 
gives you the opportunity to work with technologies that you may not otherwise 
work with in your day job. It connects you with a large community of developers 
working on a diverse array of challenges. Many of these developers are happy to 
share their knowledge with folks looking to learn something new. 


In this chapter, we look at ways to explore the range of open source software 
GitHub has to offer. We not only look at ways of discovering repositories you may 
want to use in your own projects, but also provide tips for finding repositories you 
may want to contribute to. 
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Exploring GitHub 


The Explore page on GitHub, located at https: //github.com/explore, is a great 
starting point to discover repositories that may align with your interests. It con- 
tains a mix of human and algorithmically curated content. Figure 9-1 shows a 
portion of the Explore page. 


Pullrequests Issues Marketplace Explore 


wi Kel 
She connected Wh) SA) > 


donors with people EVENT 


i ; d R Join the world's largest game 
= behind on their bills pes Seas 
Build your own Octocat Meet Tiffani Ashley Bell > 


Get together and create games with Global 
Take a break from your build and create an Game Jam in hundreds of locations worldwide 
Octocat that's all you. Jan 25 - 27. 





Based on your interests 








B= Microsoft / vscode EB benbalter /jekyll-avatar B rsdn / CodeJam Ø ForNevVer / wpf-math 5 
Visual Studio Code A Jekyll plugin for rendering GitHub Set of handy reusable .NET NET library for rendering Moc 
kerna P9033 avatars components that can simplify your mathematical formulae using the met 
kao pa daily work and save your time when LaTeX typsetting style, for the WPF ka 
you copy and paste your favorite framework 
helper methods and classes from tm py 
one project to another 
FIGURE 9-1: km Po 
The Explore page Based on people you follow Based on repositories you've viewed Based on repositories you've viewed Based on repositories you've viewed Base 
on GitHub. 





In the next several sections, we describe each section of the Explore page and its 
significance. Where it makes sense, we cover what you need to do to make your 
repository a candidate for inclusion in the section. 


Exploring the headline section 


The headline section contain three featured sites. At the time of writing, it featured 


>> Alink to Build Your Own Octocat app at https: //myoctocat . com 
>» A profile of Tiffany Ashley Bell, founder of the Detroit Water Project 


>» A link with information about an event, The Global Game Jam 


You can check back on this section to discover interesting apps, people, and events 
that GitHub feels are worth featuring. 
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FIGURE 9-2: 
The Discover 
page on GitHub 
with repository 
recommenda- 
tions. 


TIP 


Discovering repositories 


The next section under the headlines displays a selection of repositories based on 
your interests. This selection is pulled from the Discover page (https: //github. 
com/discover), an algorithmically curated page of recommendations specific 
to you. 


Click the heading, based on your interests, to see the full list of your recommen- 
dations (see Figure 9-2). 


(æ) arch or ju Pull requests Issues Marketplace Explore S+ A 


Discover repositories 


Recommendations are based on your stars and people you follow 


Based on people you follow K Star 


EE Mi 
H Microsoft/vscode 


Visual Studio Code 
editor electron visual-studio-code typescript microsoft 


@ TypeScript 67,714 MIT 255issuesneedhelp Updated 38 minutes ago 


Based on repositories you've viewed K Star 


Ea benbalter/jekyll-avatar 


A Jekyll plugin for rendering GitHub avatars 
jekyll jekyll-plugin github avatars github-pages 


@ruby kao AMT tissueneedshelp Updated 4 days ago 


Based on repositories you've viewed K Star 


BA rsdn/CodeJam 
Set of handy reusable .NET components that can simplify your daily work and save your 
time when you copy and paste your favorite helper methods and classes from one project 
to another 











GitHub employs machine learning techniques to generate a list of recommenda- 
tions based on repositories you’ve starred, contributed to, and viewed. The rec- 
ommendations also factor in the people you follow on GitHub. Chapter 17 goes into 
more detail on these actions and why they’re important. 


To improve the recommendations, be mindful of the repositories you star and the 
people you follow. 


Trending repositories 


The next section on the Explore page includes a list of the top 25 trending reposi- 
tories. Click the heading to visit https: //github.com/trending, a page where 
you can discover repositories and people that are trending across GitHub. 
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TIP 


FIGURE 9-3: 


List of topics for a 


158 


repository. 


Why only 25 trending repositories? To have more than 25 trending repositories 
would dilute what it means to be trending. Also, it takes a lot to compute trending 
repositories, so limiting it keeps the cost low. 


This page lets you filter trending repositories based on the primary language of 
the repository. If you’re interested in the trending JavaScript libraries, click the 
Other Languages button and select JavaScript. 


The Trending button at the top of the page defaults to today, but you can click it 
to see what’s been trending for the week and month. 


To determine what’s trending, GitHub looks at a variety of data points, such as 
stars, forks, commits, follows, and pageviews. GitHub weighs these data points 
appropriately and factors in how recent the events were, not just total numbers. 


Exploring topics 


The Popular topics section lists the most popular topics on GitHub. A topic is a 
user-applied category for a repository. A topic gives people more information 
about what a repository is about. A repository owner can specify multiple topics 
for a repository. The concept is very similar to tags or issue labels. 


Figure 9-3 shows the list of topics for the thewecanzone/GitHubForDummiesReaders 
repository. Admins for the repository see a Manage topics link that lets them add 
or remove topics for the repository. 


Pullrequests Issues Marketplace Explore 





thewecanzone / GitHubForDummiesReaders @Qwatchy 0 wWwStar 3  YFork 2 





<> Code Issues 0 Pull requests 2 Projects 0 Wiki Insights Settings 


This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! Edit 


github education markdown novice Manage topics 





Manage topics link 


When you add topics, you type a portion of a topic name, and GitHub offers sug- 
gestions based on the topics that others use within GitHub. Figure 9-4 shows an 
example where we type novice, and GitHub suggests other topics with the word 
novice in them. 


Visit the Topics page at https: //github.com/topics to see the most used topics 
on GitHub. 
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FIGURE 9-4: 
A list of 
suggested 
topics. 


FIGURE 9-5: 
Topic page for 
NodeJS. 


ws) Pullrequests Issues Marketplace Explore 


<> Code Issues 0 Pull requests 2 Projects 0 Wiki Insights 
This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! 


Topics (separate with spaces) 

Add topics to categorize your repository and make it more discoverable. 
github x education x markdown x novice 
novice 
noviceparadigm 
novicell 
novice-guide 
novicell-debounce 
novicell-mapbuilder 
novicell-frontend 
novicell-cookie-info 
novicell-overlay 


novicell-map 





J thewecanzone / GitHubForDummiesReaders © watch > 


wstar 3 Yrork 2 


Edit 


Done 


3 days ago 
yonth ago 


days ago 


P 


Clicking a specific topic is a great way to explore repositories related to a subject 
that you’re interested in. For example, if you’re interested in exploring Node. js 
repositories, you can navigate to https: //github.com/topics/nodejs. 


Topics are open-ended in that people can apply any topic they want to a reposi- 
tory. However, popular topics are often curated. For example, the Node. js topic 
page has a description and logo (see Figure 9-5). Figure 9-5 also shows the many 
options for sorting the topic’s repositories via the expanded Sort button. 


(%) Pull requests Issues Marketplace Explore 


Node.js 


generation of developers to create servers, command-line tools, desktop apps, and even robots. 


K Star Suggestedits Created by Ryan Dahl Released May 27, 2009 


Sort options 
freeCodeCamp / freeCodeCamp Best match 


The https://www-freeCodeCamp.org open source codebase and curriculum. Lea 
together with millions o.. 


Most stars 


Fewest stars 


learn-to-code nonprofits programming nodejs react d3 careers 
Most forks 


© JavaScript Updated 2 hoursago 42 issues need help 
Fewest forks 
Recently updated 
electron / electron 
@ Build cross-platform desktop apps with JavaScript, HTML, and CSS 


Least recently updated 


electron javascript c-plus-plus html css chrome nodejs v8 





@C++ Updated 2hoursago 16 issues need help 


Node.js is a tool for executing JavaScript in a variety of environments. JavaScript had humble beginnings as a language that 
lived only in web browsers, but the Node.js project has expanded its reach and helped make it the most popular programming 
language in the world. Node.js extends the creative potential of people with web development experience, enabling a new 


REPOSITORIES 57,691 Language: All ~ Sort: Best match + LEARN ABOUT NODEJS 


See more topics 
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The topic descriptions and logo are themselves specified in an open source 
repository. Anyone can suggest edits for an existing topic description. Anyone can 
propose a topic description and logo for a new topic. 


The descriptions and logos are located in the https: //github.com/github/ 
explore repository. For example, the topic logo and description for the Node.js 
repository is located in this directory https: //github.com/github/explore/ 
tree/master/topics/nodejs. 


Exploring Marketplace apps 


The next section of the Explore page lists popular Marketplace apps. You can add 
these apps to a repository to enable more capabilities and improve the workflow 
when working with the repository. 


Chapter 15 covers the GitHub Marketplace in more detail. 


Exploring Events 


The Events section lists a selection of upcoming GitHub affiliated events, such as 
GitHub Universe (GitHub’s yearly flagship conference), GitHub Satellite (smaller 
GitHub community events hosted around the world), and others. 


Check this page often to find out about future events, which can be a great way to 
connect with the larger GitHub community. 


Exploring collections 


The next three sections are curated collections. At the time of writing, they are 
currently Front-end JavaScript frameworks, Learn to Code, and Probot Apps. 


Each collection is fully curated by a human. A collection may contain a list of web 
pages and repositories. The goal is to be a great starting point for learning a par- 
ticular subject in depth by listing websites for further reading and repositories 
with related code. 


For example, to edit The Learn to Code collection, suggest an edit to this file in the 
github/explore repository: 


https: //github.com/github/explore/blob/master/collections/learn-to-code/ 
index.md. 
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Getting by with help from your friends 


Exploring what others on GitHub are up to is a great way to discover interesting 
new repositories. Whether it’s your friends or other people you admire, be sure to 
pay attention to what they’re up to on GitHub. One way to do so is through stars. 


As you explore repositories on GitHub, be sure to star the ones that pique your 

interest. To see your starred repositories, go to https: //github.com/stars. 

Starring a repository not only is a good way to bookmark a repository for later 
TIP exploration, but it also is a nice way to show a repository some recognition. 


On the bottom left of the stars page is a grid of avatars for your friends on GitHub. 
Click a friend to see the repositories she’s starred. Starred repositories often sur- 
faces interesting repositories you may not have otherwise noticed. 


You can also visit the profile page for your friends or other developers that you 
admire and look at their pinned repositories. Pinned repositories are repositories 
that a person explicitly chooses to feature. Figure 9-6 shows the pinned reposito- 
ries for Phil, one of the authors of this book. 


Enterprise Explore Marketplace Pricing Sign in 


ws) Why GitHub? 


Sign up | 





Overview Repositories 54 Stars 41 Followers 2.6k Following 15 





Pinned repositories 


SeeGit github/Scientist.net 


A NET library for carefully refactoring critical paths. It's a 
port of GitHub's Ruby Scientist library 


SeeGit - The Git Repository Visualizer 





~ @c# w4a2 Y102 @c# wik Yo2 


R 





Working from home 


Give us feedback RouteMagic Rothko 


Utility Library to get the most out of ASP.NET Routing. An abstracted library for interacting with the file system, 


registry, etc. 


Phil Haack 


Haacked @ce km Yas @ce k7 Yis 


Block or report user 


FIGURE 9-6: 
Profile page for 


* m 


B Not much to say that | haven't 


Encourage 


A bit of encouragment added to Visual Studio 


encourage-atom 


An Atom extension that adds little encouragements while 
you work 


said at http://haacked.com/about/ @c# weo Y¥35 @ JavaScript %22 Y10 


Phil, one of the 
authors. 











Finding Places to Contribute 


Some of you may be ready to move beyond just using open source code and are 
ready to hone your skills by contributing back to open source. How do you find a 
project to contribute to? 
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Exploring interesting repositories on GitHub comes into play when looking for a 
place to contribute. The only difference is that you’ll have to narrow your explo- 
ration down even more when looking for a place to contribute. 


The first thing to ask yourself is what type of repository do you want to contribute 
to. Answering this question can help narrow and guide your search. 


There are many valid reasons for contributing to open source. One or more of the 
following may apply: 


>> | want to get involved in OSS in general and learn how to contribute. 

>> | want to help improve a project that | use in my day-to-day work. 

>» | want to support a project that does good in the world. 

>> | want to expand my skills by working in a technology | don’t normally get to. 


>> I'm just bored and want to contribute to something cool. 


No matter your reason for contributing to open source, a good place to start when 
approaching a new repository is to look for low-hanging fruit. Many repositories 
have some manner to indicate issues that would be great for first-time contribu- 
tors. Often, they apply a label, such as help—wanted or up—for-grabs. 


In fact, some websites scour issues labeled as such and make them searchable to 
those looking to get started with open source. The Up For Grabs website at 
https: //up-—for—grabs.net is one example. 


The site has a search tool for filtering issues by project, label, and tag. Figure 9-7 
shows an example where we’re looking at all projects that have a beginner label 
and are tagged with javascript. 


Several repository results are displayed along with the label that matched the 
filter. Click the label for the repository result to see the specific issues for that 
repository with that label. Filtering issues is a good way to find a concrete issue to 
work on as a beginner. 


A GitHub topic named help-wanted, which is at page, https: //github.com/ 
topics/help-—wanted, lists repositories that are looking for help. When you visit a 
project that needs help, visit the issues page to look for potential issues you can 
help with. 
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FIGURE 9-7: 
Up for grabs filter. 


FIGURE 9-8: 
Visual Studio 
Code Issues 
filtered by the 
good first 
issue label. 








Pret 


Filter by name: 


Select a project 
Filter by label: 
beginner x | beginner friendly x || Beginner Suitable x |{ bite-sized x 
Filter by tags: 
javascript (187) x 
Popular tags: 
-NET (213) javascript (187) C#(124) web(105) F#(99) python (91) 


www.dartlang.org 


Awebsite covering the Dart language and common libraries, for developers 
of Dart libraries, web apps, server-side code, and mobile (Flutter) apps. 


dart, javascript, website 


cdnjs 





f°) The most famous free and open source web front-end libraries cdn 


cdn, js, css, libraries, web, frontend, javascript 


OpenDota UI 











Mea) Aweb interface for viewing Dota 2 data 





For example, Figure 9-8 shows the issue tracker for the Visual Studio Code open 
source project. At the top is a message that mentions the project’s contribution 
guidelines and a helpful tip to look for issues labeled help wanted or good first 
issue. Figure 9-8 shows the issues filtered by the good first issue label. 





Microsoft / vscode © Watch 2,650 W Unstar 


Code @ Issues 4,594 Pull requests 185 Wiki Insights 


Ñ Want to submit an issue to Microsoft/vscode? 


If you have a bug or an idea, read the contributing guidelines before opening an issue. 
Issues labeled help wanted or good first issue can be good first contributions. 


Filters ~ is:open is:issue label:"good first issue" Labels Milestones 


B Clear current search query, filters, and sorts 


© 28 Open v 226 Closed Author ~ Labels ~ Projects ~ Milestones ~ 


© git: several hints and dialogs don't appear when using keyboard shortcut commit [bug] git 
good first issue help wanted polish ux 
#66620 opened 6 days ago by flurmbo “P Backlog 


© auto-link tooltip of integrated terminal does not disappear under some conditions [bug] 


good first issue help wanted [IC OSETIN] 





#66421 opened 11 days ago by rinsuki Backlog 


67,771 YFork 9,042 


Dismiss 


New issue 


Assignee ~ Sort ~ 


(mE) 


B 
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Surveying a Project for Contribution 


Suppose that you decided that you want to contribute to a particular project. What 
are the next steps? For this example, we look at the Visual Studio Code repository 
at https: //github.com/microsoft/vscode. 


Reading the CONTRIBUTING guide 


As the suggestion on the Issues page notes, read through the contributing guide- 
lines first. 


The contributing guidelines message displayed on the Issues page is controlled by 

a convention. Add a file named CONTRIBUTING. md to the root of the repository, a 

folder named docs, or a folder named . github in order to specify contributing 
TIP guidelines for a repository. 


Visual Studio Code’s contributing guidelines are located at https: //github.com/ 
Microsoft/vscode/blob/master /CONTRIBUTING. md. 


Like many contributing guides, the guide provides a high-level overview of how 
to make contributions to the project. It notes that contribution is more than just 
writing code. To emphasize that philosophy, the guide starts by letting you know 
where to ask questions about the project. The guide address the key topics: 


>> Where to ask questions 
>> Where to provide feedback 
>> Where and how to report issues 
>» Details about their automated issue management 
>» A link to a guide on how to contribute code 
This format is pretty common for contributing guides. Sometimes, a smaller proj- 


ect will also include how to contribute code in the main document, but for larger 
or more complex projects, contributing code is a big topic. 


Reading the contributing code guide 


The VS Code project keeps its code contribution guide in a wiki located at https: // 
github.com/Microsoft/vscode/wiki/How-to-Contribute. 
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TIP 


If you plan to contribute code, read through this guide carefully. 


The guide has the key information yov’ll want to code on the project and is struc- 
tured in a fashion pretty common among open source projects: 


>> Building the code 

>> Running the code 

>> Debugging the code 

>» Running the automated tests 


>> Running automated code analysis, such as linting 
The next section covers the code contribution workflow: 


>» Following the branching strategy 
>> Creating pull requests 


>> Packaging code for distribution 


Reading the code of conduct 


The contributing guide focuses on the mechanics of making a contribution. Many 
projects now also include a CODE_OF_CONDUCT.md file. This file lays out expecta- 
tions for those who participate in the project. It sets the behavioral norms for the 
project and a resolution process in cases where violations of the norm occur. 


VS Code uses the Microsoft Open Source Code of Conduct located at https: // 
opensource.microsoft.com/codeofconduct. 


Adding a code of conduct to your own repository is easy. If you add a new file on 
GitHub using the browser and name the file CODE_OF_CONDUCT.md, GitHub dis- 
plays a code of conduct selection drop-down list with two choices: the Contributor 
Covenant and the Citizen Code of Conduct. 


You can also visit the community page for any public repository to add a code of 
conduct. Go to the community page by appending /community to the end of the 
repository URL. For example, type https://github.com/microsoft/vscode/ 
community to see w the project has a code of conduct. If it doesn’t, the page gives 
you the opportunity to propose one. 
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Setting Contributor Expectations 
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REMEMBER 





REMEMBER 


REMEMBER 


After you’ve read the code of conduct and contribution guides, you’re ready to dive 
in and make some contributions. Now’s a good time to make sure that you have 
clear expectations for how the process will work. 


These general guidelines for contributors may not be spelled out in a contributing 
guide, but are more the result of collective wisdom gathered from working in open 
source for a long time. 


They won't fix every issue 


Many, if not most, projects have limited resources, and their priorities may not 
align with your priorities. It’s important to keep all that in mind when you file an 
issue. On the one hand, opening a good issue takes time and energy. A well- 
written issue that describes a problem clearly with clear steps to reproduce the 
issue is very valuable to a project, so it’s understandable that people who write 
issues feel invested in them. 


On the other hand, the fact that an issue may not be fixed is why we note that 
writing an issue is a contribution. It’s not an exchange of one thing for another, 
but it’s a gift. And as such, you can’t expect much in return. Good project main- 
tainers will thank you for filing an issue and note whether they know of any work- 
arounds at minimum, but they do not owe you a fix. Do not take it personally if an 
issue you file is labeled as won't fix. 


They won't merge every pull request 


Submitting a pull request is the culmination of a lot of work. In order to submit a 
proper pull request, a developer had to spend the time to get the code working on 
his own machine, understand the code well enough to make a change, write the 
change, and then submit it. 


Being disappointed when the repository maintainers then reject the pull request 
is understandable. Remember, though, they’re under no obligation to accept your 
pull request. Yes, you put a lot of time into the pull request, but they’ll have to own 
the code change for the lifetime of the project. 


Having a pull request rejected should be a very rare occurrence. You and the project 
maintainers can do a lot beforehand to avoid a rejected pull request. The first step 
starts with communication. Before you start work to resolve an issue, comment on 
the issue with your intentions. Indicate your general plan of attack. Make sure 
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that someone related to the project responds and agrees with your general 
approach. This communication reduces the likelihood that you go off and work on 
something in a matter completely contrary to the project. 


Don’t stop your communication there, though. Keep it going. As soon as you have 
a commit or two, push it to a pull request and make sure the pull request is clearly 
marked as a work in progress. Marking the pull request as a work in progress lets 
you continue to get feedback as you go and ensure that you’re on the right path. It 
minimizes the time spent going down the wrong path. 


Finally, make sure that you’re following all their contribution guidelines, style 
guidelines, and so on. This is their project, and they will own the code if they 
choose to merge your PR in. This is not the time and place to try to advocate for 
your way of working or your personal code style. 


They don’t owe you anything 


One of the biggest challenges of being a maintainer of a popular open source proj- 
ect is the sense of entitlement expressed by many people who use the software. 


In most cases, the maintainers are all volunteers working on the project on the 
side. This isn’t always the case. Sometimes, they’re paid employees working on an 
open source project. But chances are, you are not the one paying them. They don’t 

REMEMBER OWe you a feature. They don’t owe you a bug fix. They don’t owe you anything. 
And you should treat them accordingly. 


Of course, the maintainers of a well-run project will try to go out of their way to 
accommodate people who participate in a project. It’s only natural that they want 
most people involved to be happy. Open source projects benefit from mind share 
and more contributors, so it’s often in their best interests to not take a hard line 
and try to get you that feature if it fits their roadmap and priorities and isn’t too 
much trouble. So it’s not wrong to ask for things. It’s not wrong to make a strong 
case for things you want. But at the end of the day, you don’t pay them, and they 
don’t owe you a thing. 


Keeping Tabs on a Project 


When you’re a contributor to a project, it’s good to keep tabs on how the project is 
doing. One way is through GitHub notifications. Chapter 1 covers how to manage 
notification settings. GitHub can send notifications for new issues, new comments 
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on pull requests, and so on. It’s important to manage your notification settings 
based on your interest level in the project. 


While GitHub may be the hub of open source, a lot goes on outside of GitHub 
related to an open source project. You may want to look at the places where a proj- 
ect lives outside of GitHub. For example, many projects have a Twitter account you 
can follow. Some projects have a public Slack instance where you can chat with the 
maintainers and others who use the project. You also may want to read the blogs 
of the maintainers of those projects to keep on top of the latest developments. 
Many projects and project maintainers still publish RSS feeds, an ancient technol- 
ogy that makes it possible to keep up with a site. 
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IN THIS CHAPTER 


» Setting up a repository for OSS 





» Managing OSS workflows 


» Ending an OSS project 


Chapter 10 
Starting Your Own OSS 


here comes a point in many developers lives when they have their own code 

to share with the world. Many different approaches and motivations may 

drive a person to share code. In some cases, a person may write some code 
they think others will find interesting and just “toss it over the wall” without any 
intent to take contributions back. On the other end is the case where someone 
wants to start a real movement with large numbers of contributors. 


Whatever your motivation, the only requirement for open source software is to 
choose a license that complies with the Open Source Definition (OSD). You can 
find the definition at https: //opensource.org/osd. The Open Source Initiative 
(OSI) has a process for approving licenses, and its site lists a plethora of licenses. 


But for the life of most open source software, choosing a license is just a starting 
point. A lot more goes with managing an open source project. In this chapter, we 
cover what it means to start an open source project on GitHub, maintain it, and if 
it comes to it, sunset it. 


Creating an Open Source Repository 


When you create a repository with the intent to make it open source, it’s common 
to make the repository public and select a license during the repository creation 
process. 
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FIGURE 10-1: 
Home page for 
our soon-to-be 

open source 

repository. 


Sometimes it is preferable to defer those choices to later. Perhaps you want to set 
up your repository right before you make it public to the world. Or you may want 
to spend more time thinking about the license. The following sections focus on the 
scenario of turning an existing private repository into an open source one. We 
assume that you’ve already created a repository with a README . md file, but didn’t 
make the repository public nor did you choose a license. (If you haven’t, see 
Chapter 3.) 


Adding a license 


The only requirement that software has to be considered open source is to have an 
open source license. GitHub makes adding a license to an existing project easy. 


Figure 10-1 shows the home page for a private repository without a license. To add 
a license: 


1 ə Click the Create new file button. 


After you click the button, GitHub prompts you to name the file. 





ws) Pullrequests Issues Marketplace Explore A ++ 8 X 
ĝ® FakeHaacked / best-example Private @unwatchy 1 wkstar 0 YFork 0 
<> Code Issues 5 Pull requests 1 Projects 0 Insights Settings 
An example for GitHub For Dummies Edit 
Manage topics 
D1 commit P 2 branches © 0 releases 
Branch: master ~ New pull request = files Find file 
f Haacked Add a descriptive README file Latest commit b692062 16 days ago 
E README.md Add a descriptive README file 16 days ago 
README.md f 
The Best Example Ever 
Which will be a part of the best commit ever. 














Create new file button 
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FIGURE 10-2: 
Choose a license 
template button 

magically appears. 


FIGURE 10-3: 
The license 
chooser page. 


2. Type your filename. 


For this example, we name ours LICENSE. GitHub notices you are attempting 
to create a license file and helpfully adds a button to the right labeled Choose a 
license template, as shown in Figure 10-2. 








® FakeHaacked / best-example Private O©unwatch~ 1 wkstar 0 YFork 0 
<> Code Issues 5 Pull requests 1 Projects 0 Insights Settings 

best-example [uicensemd | or cancel Choose a license template 
<> Edit new file © Preview Spaces $ 2  Nowrap s 











3. Click the Choose a license template button to see a list of license templates. 


The three most common licenses used on GitHub are listed first in bold, as 
shown in Figure 10-3. Chapter 3 provides a brief guide on choosing a license, 
but this page has a link to a more detailed guide to help you pick which license 
best fits your project. 


The three most popular licenses on GitHub 


Pull requests Issues Marketplace Explore 


@ FakeHaacked / best-example Private @unwatchy 1 Astar 0 YẸ Fork 


Code Issues 5 Pull requests 1 Projects 0 Insights Settings 


Add a license to your project 





Apache License 2.0 


GNU General Public License 
v3.0 


“SED Choose a license to add to your project 





BSD 2-Clause “Simplified” Select a template on the left to get started. 
License 
Learn more abou] which license best fits your project. 





BSD 3-Clause "New" or "Revised" 
License 


Eclipse Public License 2.0 


GNU Affero General Public 
License v2.0 





o 








Link to more information on choosing a license 
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FIGURE 10-4: 
The license 
information page. 


4. After you know which license you want, click the license to view informa- 
tion about the license. 


This page includes a high-level summary with bullet points about the key traits 
of the license. This overview helps you gain an understanding of the license 
without having to wade through all the legalese. 


Of course, the page also presents the full text of the license for those who 


relish legalese. On the right are fields required by the license. 


5. Enter your information in the fields to customize the license to your 


situation. 


You can see an example of this page in Figure 10-4. 


High-level summary of the license attributes 





Add a license to your project 


Apache License 2.0 


GNU General Public License 
v3.0 


MIT License 


BSD 2-Clause "Simplified" 
License 


License 


Eclipse Public License 2.0 


GNU Affero General Public 
License v3.0 


GNU General Public License v2.0 





BSD 3-Clause "New" or "Revised" 


A short and simple permissive license with conditions only requiring preservation 
of copyright and license notices. Licensed works, modifications, and larger works 
may be distributed under different terms and without source code. 
Conditions 


Permissions Limitations 


v Commercial use 
v Modification 

v Distribution 

v Private use 


X Liability © License and copyright 
X Warranty notice 


This is not legal advice. Learn more about repository licenses. 


MIT License 


Copyright (c) (2038) CEET 


Permission is hereby granted, free of charge, to any person 
obtaining a copy of this software and associated 
documentation files (the "Software"), to deal in the Software 
without restriction, including without limitation the rights to 
use, copy, modify, merge, publish, distribute, sublicense, 
and/or sell copies of the Software, and to permit persons to 





To adopt MIT License, enter your 
details. You'll have a chance to 
review before committing a LICENSE 
file to a new branch or the root of 
your project. 


Year @ 
2019 


Full name © 


Phill Haack 


Review and submit 











The text of the license with your information filled in 





License template fields and button to move to next step 


6. After you're satisfied with everything, click the Review and submit 


button. 


You return to the file creation page with the text of the license filled in. 


7. Scroll down to enter your commit message and click Commit new file to 
create the license file. 
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Adding contributor guidelines 


Another useful document to include in your repository is a file named 
CONTRIBUTING.md. This file provides information on how to contribute to your 
project. It should include information such as where people should ask questions 
and where to provide feedback. 


Chapter 9 provides more details on what a contributor can expect to find in a 
CONTRIBUTING.md document. That chapter is a good place to start for your own 
project’s contribution guidelines. 


A robust CONTRIBUTING.md document will save you and your future contributors a 
lot of headache and time. Be sure to revisit it from time to time to make sure it’s 
up to date. 





REMEMBER 


Adding a code of conduct 


A code of conduct makes behavioral expectations clear for everyone who partici- 
pates with your project, whether they contribute code, comment on an issue, or 
otherwise interact with others on your repository. A code of conduct sets the tone 
for the type of open and welcoming environment you want to foster for your 
project. 


To add a code of conduct, follow the same process as you do when adding a license, 


but name the file CODE_OF __CONDUCT . md. (See the “Adding a license” section, ear- 
lier in this chapter.) This process is covered in Chapter 9 as well. 


Making a Repository Public 


At this point, your repository has the basic items it needs to go public. To change 
a repository from private to public: 


1. visit the Settings page for your repository. 


2. Scroll to the bottom of the Settings page to reach the Danger Zone, as 
shown in Figure 10-5. 
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FIGURE 10-5: 
Danger zone: 
where you can 
make a private 
repo public. 


WARNING 


FIGURE 10-6: 
Confirmation to 
convert a private 
repo public. 





Upgrade to GitHub Pro or make this repository public to enable Pages. Upgrade now 





Danger Zone 
Make this repository public Make public 
Make this repository visible to anyone. 
Transfer ownership Transfer 


Transfer this repository to another user or to an organization where you have the ability to 
create repositories. 


Archive this repository 


Archive this repository 
Mark this repository as archived and read-only. 


Delete this repository 


Delete this repository 
Once you delete a repository, there is no going back. Please be certain. 

















3. Click the Make public button to initiate making a repository public. 


This step is a potentially dangerous operation because you may inadvertently 
expose information to the world you'd rather keep private. So make sure you 

really are ready to make this repository public. If you created it with the intention 

of making it public from the beginning, the repository shouldn't contain any secrets. 


GitHub displays a confirmation dialog after you click the Make public button asking 
you to type the name of the repository to confirm this change, as seen in Figure 10-6. 


4. Type the repository name and then click the | understand, make this 
repository public button to make the repository public. 


Thee setting page now has a section that will come in handy as you manage 
your new open source project. 


Make this repository public 
A Warning: this is a potentially destructive action. 


o The code will be visible to everyone who can visit 
https://github.com 

o Anyone can fork your repository. 

© Your changes will be published as activity. 


Please type in the name of the repository to confirm. 





[ best-examle 











I understand, make this repository public. 
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Enforcing a Code of Conduct 


WARNING 


TIP 





REMEMBER 


A code of conduct is a great way to communicate behavioral expectations for a com- 
munity. But a code of conduct isn’t enough to create a healthy community on its 
own; you have to enforce it. 


It would be wonderful if you never had to enforce your code of conduct. Most 
people who participate in your project will be helpful and kind. However, as your 
project grows and more people get involved, it’s almost inevitable that you’ll have 
to step in. 


Responding with kindness 


Keep in mind that even when someone acts in a matter that doesn’t fit in the spirit 
of your code of conduct, they may not necessarily be malicious or a bad actor. 
Maybe they’re having a bad day, and they took it out on your repository. That 
doesn’t excuse their behavior, but it is relatable. We’ve all done it. 


If someone makes an off color or angry comment in an issue in your repository 
that goes against the type of community you want to foster, it’s often disarming 
to reply back with a kind response that expresses empathy for their situation, but 
is clear that the comment doesn’t meet community guidelines. Be specific in how 
it does not meet the guidelines and if you can, suggest an alternative approach 
they could have taken. 


For example, if someone comments on the repository that the maintainer must 
hate other people because they haven’t fixed a particular bug, you can respond 
with something like “Personal attacks are not welcome in this repository. We are 
all volunteers trying to work on this in our spare time. I understand that you are 
frustrated. Instead of a personal attack, perhaps write about how the bug affects 
you and why that is frustrating to you.” 


But always remember, you don’t owe anybody anything. You’re not there to be a 
punching bag for people. If they’re abusive or if you’re simply tired of a thousand 
paper cuts of negative comments, rather than respond while angry, take a break. 
Walk away. Ask for help. Your own mental well-being comes first. 


Leveraging the ban hammer 


It would be nice if a kind admonishment worked in every situation (see preceding 
section), but sometimes tempers flare. We’re all human, and sometimes we lose 
our temper. So will people who participate in your repository. This situation is 
where temporary interaction limits come in handy. 
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FIGURE 10-7: 
The set of 


interaction limits. 


176 


REMEMBER 


At the very bottom of the Settings page for your public repository (this setting 
doesn’t exist for a private repository) is a moderation section with a link to Inter- 
action limits. Click this link to see the set of limits available. Figure 10-7 shows 
this page after enabling the Limit to existing users option. 





FakeHaacked / best-example @©unwatchy 1 wW&Star 0 YFork 0 
Code Issues 5 Pull requests 1 Projects 0 Wiki Insights Settings 
Options Temporary interaction limits 
Collaborators 
Temporarily restrict which users can interact with your repository (comment, open issues, or create pull 
Branches requests) for a 24-hour period. This may be used to force a "cool-down" period during heated discussions. 
Webhooks 


Limit to existing users 

Notifications © Enabled with 1 day remaining. Disable 
Users that have recently created their account will be unable to interact with the repository. 

Integrations & services 


Deploy keys Limit to prior contributors 
Users that have not previously committed to the repository's master branch will be unable to interact with Enable 
the repository. 

Moderation 


Interaction limits © Limit to repository collaborators 


Users that have not been granted push access will be unable to interact with the repository. 


Enable 











These limits are not permanent bans. They are cool-down periods. This tool is 
great to use when a discussion or an issue gets a bit too heated. It gives everyone 
time to cool down and prevents the discussion from running even further out of 
control. 


Blocking users 


Every once in a while, you may encounter a truly abusive person in your project. 
You’ve tried to kill them with kindness. You’ve tried the 24-hour cool-down periods, 
but they persist in being rude or antagonistic. It is time to block or report the user. 


To block or report the user: 


1. Click the user's name next to their comment to visit their profile page. 


Underneath their profile picture is a link to block or report the user, as shown 
in Figure 10-8. 


2. Click the link to block or report the user. 


A dialog box with two options appears: Block user or Report abuse, as shown 
in Figure 10-9. 
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FIGURE 10-8: 
Profile page with 
link to block or 
report user. 


FIGURE 10-9: 
Dialog box with 
Block user and 
Report abuse 
buttons. 


TIP 


3. Click Block user to immediately block the user. 


Blocking a user denies a user from accessing your activity and repositories. 

It also prevents them from sending you notifications, such as when they @ 
mention your username. They pretty much no longer exist as far as you are 
concerned, and vice versa. For more details on what happens when you block 
auser,visithttps : //help.github.com/articles/blocking-a—user-from-your 
personal-account/. 


rw) Pull requests Issues Ma} 


Overview Repositories 8 Stars 








Popular repositories 





git-demo 
Demo for DEVDAYS 
@c# w2 Y2 

This is not the real 

Haacked FizzBonacci 

FakeHaacked An implementation of Fibonacci as a demo 
@c# 

Follow 

Block or report user i 

SeeGit 


Forked from Haacked/SeeGit 
© Your imagination 
® http://haacked.com/ 


SeeGit - The Git Repository Visualizer 


@c# 











Link to block or report user 


Report or block FakeHaacked 


Hide content and notifications Contact Support about this 
from this user. user's behavior. 


Block user Report abuse 





You can also block users, see a list of users you currently have blocked, and unblock 
users from your account Settings page by going to https://github.com/ 
settings/blocked_users. 
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Writing a README.md File 


The README . md file holds a special significance on GitHub. When you visit a repos- 
itory’s home page, GitHub displays the contents of the README.md rendered as 
Markdown on the home page. The README .md contents is what visitors to your 
repository will expect to see to learn more about your project. 


Chapter 3 includes information about what should be included in a README . md file. 
It should also include links to your CONTRIBUTING.md file and your CODE_OF_ 
CONDUCT .md file. After reading this file, a person should understand what your 
project does, how to get involved, and where to go to find out more information. 


Writing Good Documentation 


178 


TIP 


One of the most neglected aspects of open source is documentation. Writing good 
docs is a great way to distinguish your project from the rest. Also, documentation 
provides a nice way for others to dip their toes into open source. One of the authors 
got his start in open source by contributing docs to a project many, many years ago. 


GitHub supports a wiki feature, but we recommend using a relatively unknown 
feature, serving a documentation site from the docs folder in the master branch 
of your repository. This feature has many benefits, but one of the big ones is the 
ability to version your documentation along with the code that it documents. 


Chapter 4 walks through building a GitHub Pages site. Serving your documenta- 
tion from the docs folder is very similar to that process. The following steps 
assume that you have a repository that is not a GitHub Pages website. Chapter 3 
walks through creating a regular repository if you need a refresher. 


Make sure to commit a file named index.md to the docs folder in the master 
branch of your repository. This feature requires that there’s already a docs folder 
before you can enable it. If you’re unclear about how to do that, Chapter 7 covers 
writing and committing code in detail. 


Navigate to your repository settings and then scroll down to the GitHub Pages 
section. By default, the Source is set to None. Click the button and select the mas- 
ter branch /docs folder option as shown in Figure 10-10 and then click the Save 
button. 
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FIGURE 10-10: 
Serving a GitHub 
Pages site from 
the docs folder. 


REMEMBER 





GitHub Pages 


GitHub Pages is designed to host your personal, organization, or project pages from a GitHub repository. 


Source 


GitHub Pages is currently disabled. Select a source below to enable GitHub Pages for this repository. Learn 
more. 


master branch /docs folder ~ Save 


+ Select source 


Il theme using the master branch /docs folder. Learn more. 
master branch 
Use the master branch for GitHub Pages. 


v master branch /docs folder 
Use only the /docs folder for GitHub Pages. 


None 
Di Disable GitHub Pages. 








You can now visit your documentation site at https: //{USERNAME}. github. io/ 
{REPO-NAME}/. To see an example of this in action, visit https: //fakehaacked. 
github. io/best-example/. 


As we cover in Chapter 4, you can select a theme and add a custom domain name 
if needed. 


Don’t forget to add a link to the docs site to your README file so that people can 
find it. 


Managing Issues 


As the word gets out about your open source project, people will start to try it out. 
And at some point, people will open issues. Congratulations! When an issue is 
opened, it means someone out there cared enough to report a bug, ask a question, 
or make a feature request. This interest is a good thing for an open source project. 


But if your project becomes very successful, the influx of new issues can start to 
get overwhelming. In the following sections, we cover some tips on managing 
incoming issues. 


Labeling issues 


GitHub provides a default set of issue labels when you create a website. 


>» bug 
>» duplicate 
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>> enhancement 
>> good first issue 
>> help wanted 

>> invalid 

>> question 

>» ready for review 


>> won't fix 


You can manage these labels by going to the Issues tab and clicking the Labels 
button. Make sure the set of labels makes sense for your project. Assigning labels 
helps you manage issues as they come in. 


Triaging issues 


As new issues are created, it’s important to triage issues. The word triage comes 
from the medical field. Merriam-Webster defines triage as “the sorting of patients 
(as in an emergency room) according to the urgency of their need for care.” 


Triaging issues is similar to triaging in a hospital. Triage, when applied to issues, 
is the process of reviewing new issues and assigning labels to indicate what type 
of issue are they (bug report, feature request, and so on.), determining their pri- 
ority, and assigning issues to people. In some cases, you may close issues you 
don’t plan to address during triage. 


Every triaged issue should have some label applied. If necessary, you can even 

create a triaged label for this purpose. Assigning a triaged label to issues that 

you’ve triaged makes it possible to see all issues that haven’t yet been triaged by 
TIP using the unlabeled filter, as shown in Figure 10-11. 





[x] Clear current search query, filters, and sorts 


@®5Open v 0 Closed Author ~ Labels ~ Projects ~ Milestones ~ Assignee ~ g 


© Set up website alerts Filter by label 
#5 opened 17 days ago by Haacked 


© Do not use an alert message 


#4 opened 17 days ago by Haacked 
Unlabeled 


© Add a contribution section to F 








#3 opened 18 days ago by Haacked Bug 
Something isn't working 
FIGURE 10-11: © The README should mention t Per 
uplicate 
Unlabeled aonana 1A days.agy Oy ERA This issue or pull request already exists 
issues filter. © Provide more details on the RE 
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FIGURE 10-12: 
Choosing an issue 
template. 


To maintain a sense of sanity, it often makes sense to schedule triage on a regular 
cadence as opposed to doing it all the time as people create new issues. 


Issue templates 


It would be great if everyone who submits an issue understood how to write up a 
proper bug report or if they understood what makes for a good feature request. 
A bug report that just says “Your stuffs is the broken” is not too helpful to the 
repository maintainer. 


To help foster good issues, you can set up issue templates that guide people filing 
issues on your repository to supply the information you need. 


In the Settings page for your repository, in the Issues section in the main pane, is 
a big green button labeled Set up templates. Clicking that button takes you to a 
templates setup page where you can choose from a set of pre-existing issue tem- 
plates or create your own, as shown in Figure 10-12. 


ow) r r f Pull requests Issues Marketplace Explore A +r &- 
O FakeHaacked / best-example ©unwatchy 1 Star 0 YWrork 0 
Code Issues 5 Pull requests 1 Projects 0 Wiki Insights Settings 


Add template: select ~ 


Bug report 
Standard bug report template 


Feature request 
Standard feature request template 


Custom template 
Blank template for other issue types 











From the templates setup page, follow these steps: 
1. Select both the Bug report template and then select the Feature request 
template. 


You should see them listed on the page. Note they're not yet active. They still 
need to be committed to the repository. 


2. Click the Propose changes button to enter a commit message for these 
templates, as shown in Figure 10-13. 
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FIGURE 10-13: 
Choosing an issue 
template. 


FIGURE 10-14: 
Choose an issue 
template to 
create an issue. 
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Bug report 


5 Preview and edit 
Create a report to help us improve 


Feature request 


j A s Preview and edit 
Suggest an idea for this project 


Add template: select ~ 





repository. 


Propose changes 


Commit changes 
Commit message 


a Update issue templates 


Extended commit message 


© © Commit directly to the master branch. 


1) Create a new branch for this commit and start a pull 
request. 


Commit changes 





Click the Commit changes button to commit these templates to the 


They are stored in a special . github/ISSUE_TEMPLATE folder. If you 
navigate to that folder, you should see two files, bug_report.md and 
feature_request .md. Take a look at the contents of those files to 
understand the structure of an issue template. 


You can create new templates by going through the previous steps or by manually 
adding a file to the . github/ISSUE_TEMPLATE directory with the same basic struc- 


ture as the existing issue template files. 


Now, when someone creates an issue on your repository, they first see a set of 
issue templates, as shown in Figure 10-14. 


(p) 


-| FakeHaacked / best-example 


Code © Issues 5 Pull requests 1 Projects 0 


Bug report 
Create a report to help us improve 


ag 


Feature request 
Suggest an idea for this project 


Don't see your issue here? Open a regular issue. 





Pullrequests Issues Marketplace Explore 


© unwatch» 1 *star 0 


Wiki Insights Settings 
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FIGURE 10-15: 

A new issue with 
the Bug report 
template filled in. 


Clicking the Get started button on one of the templates then displays the issue 
creation form, but with the contents prepopulated with the template information. 
Figure 10-15 shows an issue prepopulated with the default Bug report template. 





Issue: Bug report 


Create a report to help us improve. If this doesn't look right, choose a different type. 


ey 


Write Preview PA Bi <> D zE 





**Describe the bug** 
A clear and concise description of what the bug is. 


**To Reproduce** 

Steps to reproduce the behavior: 

1. Go to"... 

2. Click on ‘....' 

3. Scroll down to"....’ 

4 See error 

Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


ED Styling with Markdown is supported 











The contents of the issue walks the issue creator through all the information 
expected of them. Of course, the person creating the issue can always choose to 
ignore the template and put anything they want in the issue. 


Saved replies 


Often, as your repository grows in popularity and the issues start to flow in, you’ ll 
find yourself repeating responses over and over again. For example, if someone 
reports a bug, you may need them to supply a log file. If every bug report should 
include a log file, then you should mention that in an issue template. 


But even if you do, many folks will forget to include it. This situation is where a 
saved reply can come in handy. A saved reply is a canned response you can use over 
and over again. 


As of this writing, canned responses apply only to a user and are not specific to a 
repository. So you can create your own saved replies, but they will not immedi- 
ately be available to other members of your repository. 


Go to https://github.com/settings/replies to manage your list of saved 


replies. To create a new saved reply, fill in the form at the bottom, as shown in 
Figure 10-16. 
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Saved replies 


Saved replies are re-usable text snippets that you can use throughout GitHub comment fields. Saved replies can 
save you time if you're often typing similar responses. Learn more. 


Log File 
Hey please send me your log file 


MORE INFO 
Please provide more details about what you expected and what actually happens. Also, if there's a l... 


Add a saved reply 


Saved reply title 


Turn it off and on again 


iii 
iii 
Ww 


Write Preview AA B i <> D ORNS- 


Hello, IT. Have you tried turning it off and on again? 


























FIGURE 10-16: Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 
Creating a new CD Styling with Markdown is supported 
saved reply. 
To access the saved replies when responding to an issue or a pull request com- 
ment, click the arrow in the top right corner of the comment box, as shown in 
Figure 10-17. That brings up a list of your saved replies. Click the one you want to 
use to fill the comment box with that reply. 
KA Write Preview AA B i oO FEET ORNS 
i Select a reply ctrl . 
Log File all 
Attach files by dragging & dropping, selecting them, or pastir Hey please send me your log file 
CD Styling with Markdown is supported jessie tricia: dotie out ctrl 2 | 
Turn it off and on again rR 
Hello, IT. Have you tried turning it o... 
Default replies 
FIGURE 10-17: Duplicate issue im 
Selecting a saved Duplicate of 
reply ina Create a new saved reply... 
comment box. 
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Ending Your Project 


FIGURE 10-18: 
The button to 
archive a 
repository 


At some point in the life of a repository, you may want to step away from it. This 
break may happen for many reasons. Perhaps the project is no longer useful, hav- 
ing been supplanted by other better projects. Perhaps the project is a runaway 
success, but you don’t have the time to give it the attention it deserves. 


Whatever the reason, it’s important to handle the end of your involvement with 
the repository with the same care you showed in starting it. 


Archiving a project 


Archiving a project is a good option when a project is no longer all that useful to 
others. Or even if it’s still useful, but mostly complete, archiving could be a good 
option. Archiving a project indicates that the project is no longer actively main- 
tained. The code is still available to the world, and people can fork and star your 
project, but nobody can create new issues, pull requests, or push code to an 
archived repository. 


To archive a repository, go to the repository settings page: 


1. Scroll all the way down to the Danger Zone and click Archive this 
repository, as shown in Figure 10-18. 


Clicking this button displays a detailed confirmation box that describes what 
will happen if you archive the repository as shown in Figure 10-19. 





Danger Zone 





Make this repository private 
Hide this repository from the public. 


Make private 


Transfer ownership 
Transfer this repository to another user or to an organization where you have the ability to 
create repositories. 


Archive this repository Archive this repository 
Mark this repository as archived and read-only. 


Delete this repository 
Once you delete a repository, there is no going back. Please be certain. 


Transfer 


Delete this repository 
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2. Type the name of the repository and click I understand the 
consequences, archive this repository to archive it. 


Your repository is archived. 


Archive repository 
Unexpected bad things will happen if you don't read this! 


This will make the FakeHaacked/best-example repository, 
issues, pull requests, labels, milestones, projects, wiki, releases, 
commits, tags, branches, reactions and comments read-only 
and disable any future comments. The repository can still be 
forked. 


Ensure you've changed any repository settings, considered 
closing all open issues and pull requests and updated your 
README before you archive this repository. 


Once archived, you can unarchive the repository at any time. 


Please type in the name of the repository to confirm. 
FIGURE 10-19: | 
The button to 
archive a | understand the consequences, archive this repository 


repository. 








Transferring ownership 


If your project is popular with a robust set of maintainers, you may want to trans- 
fer ownership to another account rather than archive the project. Transferring 
ownerships lets the new owner have full rights to the repository and continue to 
maintain it. 


To transfer ownership: 


1. Goto your repository's Settings page and scroll down to the Danger Zone. 


2. Click the Transfer button to bring up the transfer dialog box, shown in 
Figure 10-20. 


3. Confirm the current repository’s name and type the new owner's 
username or organization name. 


The URL to the repository changes, but GitHub redirects the old URL to the 
new URL when anyone tries to visit the repository. 
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Transfer repository 


To understand admin access, teams, issue assignments, and 
redirects after a repository is transferred, see "Transferring a 
repository" in GitHub Help. 


Transferring may be delayed until the new owner approves the 
transfer. 


Type the name of the repository to confirm 


L 


New owner's GitHub username or organization name 


FIGURE 10-20: 
The transfer 
repository 
dialog box. 


I understand, transfer this repository. 
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IN THIS CHAPTER 


» Creating a GitHub organization 





» Setting up teams 


» Understanding inner-source best 
practices 


Chapter 11 


Inner-Source Your Code 
on GitHub 


hapters 9 and 10 talk about the open source community and best practices 

on GitHub.com. But if you want to keep your code private, GitHub offers 

unlimited private repositories for free, personal plans to support your pri- 
vate software development. 


In this chapter, you discover some situations where you may want to code in pri- 
vate. You also get the inside scoop on inner-sourcing your code. 


Why Code in Private? 


If we’re appropriately representing the open source community, you may be 
inclined to do everything in the public. But what if you work at a company on pro- 
prietary code? What if you’re starting a new company where you plan on selling 
software? Or, what if you’re a student, and you’re working on a group coding 
assignment? These are examples of when it may be appropriate to work in a private, 
collaborative environment, when it may be appropriate to inner-source your code. 


Inner-sourcing is really just a play on words with open source. It implies that you 
will use the same (or similar) strategies to collaborative code writing as open 


source, but you will do it on private repositories. 


CHAPTER 11 Inner-Source Your Code on GitHub 189 


Using GitHub Organizations 


190 


Depending on who you’re working with and the scope of the project, you may 
want to have access to certain GitHub features. If you’re working on proprietary 
code for a company (or code that may be a product for a future company you’re 
hoping to start), then the investment of GitHub Teams may be suitable, giving you 
private repos as part of an organization. But if you’re working with other students 
at your university on a semester-long project, then just creating a private repo 
may be good enough. 


Creating a GitHub organization 


GitHub organizations allow you to give a group of users access to a set of reposito- 
ries all at once. With features such as teams, you can also have subgroups of users 
that have different access rights to different repositories. This setup also makes 
communicating across GitHub easier because you can tag an organization (or 
team) instead of an individual person. If you’re running a large project that has 
more than one repository, organizations may be a good option for you. 


You can start an organization in one of three tiers: 


>> Team for Open Source: In this tier, you get unlimited public repositories, 
unlimited collaborators, issues and bug tracking, and project management. 
Essentially, this tier allows a core group of people who are working on an 
open source project to work together easier. If you don't need any private 
repos associated with the organization, this tier is a great option. 


>> Team: In this tier, you get everything from the previous tier, plus unlimited 
private repositories, the ability to require all your organization members 
using two-factor authentication, team discussions that don't have to be 
associated to a specific repository, access for managing groups of people, 
and advanced tools and insights into all your repositories. 


Two-factor authentication is when you're required to enter in your password 
plus perform an additional security measure to ensure it is really you logging 
in to the website. Because passwords can sometimes be hacked, organiza- 

TIP tions will often require that you use a mobile app (such as Duo Mobile or 
Google Authenticator), text-message confirmation, or a physical YubiKey to 
verify that it is you. 


>> Enterprise: This tier essentially gives you GitHub.com with the Team tier 
features, but all your data is private on a self-hosted or cloud-hosted instance 
of GitHub. (The data is not shared with the rest of GitHub.com users.) If you 
have a GitHub.com account and your company has a GitHub Enterprise 
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FIGURE 11-1: 
Inviting someone 
to join your 
organization. 


instance, you will have a separate account to log in to your company's GitHub 
instance. This tier is most likely beyond the scope of what you'll be doing in 
but you may work for a company that has this. 


You can find the tiers by clicking the plus symbol at the top right of GitHub.com 
(when you’re logged in) and choosing New organization. You see a new page 
where you can choose the organization’s name, specify a billing email address, 
and choose a tier. 


Don’t worry: If you choose the free tier, you aren’t billed anything; you won’t even 
be asked for a credit card. 


Inviting members to your GitHub 
organization 


During the organization setup process, you’re asked if you want to invite others to 
join your organization. Using their GitHub.com alias, you can search for them in 
the provided box and send them an invite. If you forget to invite someone or want 
to invite them later, you can still do so by going to the People tab on the organiza- 
tion’s home page and clicking Invite member. You can choose the permission level 
for the person you invite to your organization. Figure 11-1 shows the two options: 
Member and Owner. You can change the permission level later, if you need to. 





a The We Can Zone 


Repositories 5 APeople 1 Teams 0 Projects 0 Settings 


Invite Adrian Guthals to The We Can Zone 


Give them an appropriate role in the organization and add them to 
some teams to give access to repositories. 


© Member 
Members can see all other members, and can be granted access to 
repositories. They can also create new teams and repositories. 


Owner 
Owners have full administrative rights to the organization and have complete 
access to all repositories and teams. 








Send invitation 4 seats left —Buy more 
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TIP 


FIGURE 11-2: 
Invitation request 
from the invitee’s 

account. 


Figure 11-1 also shows the number of remaining seats for your organization at the 
bottom of the page. If you’re on the free tier, you have unlimited seats, but if 
you’re on the paid tier, then you have only the number of seats you’ re paying for. 


The Teams tier has a minimum of five seats at a set price. If you want to add more 
seats, you can, but you always start with five. 


After you invite someone to your organization, they will receive an email notifica- 
tion with a link to accept the invitation, or they can go to the organization’s 
GitHub home page to accept the invitation. For example, in Figure 11-1,we invited 
Adrian to be a part of The We Can Zone organization because he helps manage all 
the writing projects that we work on. When he visited https: //github.com/ 
thewecanzone while logged in to his GitHub account, he saw a banner and View 
invitation button at the top of the page. Clicking the View invitation button, he 
was taken to a new page, shown in Figure 11-2, where he was able to first see what 
kind of access the owners of the We Can Zone organization would have to his 
GitHub account information if he were to join. 





We caw 





You've been invited to the The We Can Zone organization! 


Invited by Sarah Guthals 


Join The We Can Zone 


&) Owners of The We Can Zone may be able to see: 


e If you have two-factor authentication enabled or not 
Your public profile information 

Certain activity within this organization 

Country of request origin 

Your access level to repositories within the organization 
Your IP address 











Viewing repositories for your organization 


Repositories is the default tab on your organization home page. This page shows 
you all the repositories associated with this organization. For example, if you go 
to the Microsoft organization home page on GitHub (https://github.com/ 
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FIGURE 11-3: 
Repositories 
associated with 
the Microsoft 
organization. 


microsoft), you find more than 2,000 repositories and more than 4,000 people 
involved in open source projects for Microsoft (see Figure 11-3). 





BB Mi ft Report abuse 
Open source, from Microsoft with love 
Redmond, WA https://opensource.micr opensource@microsoft. Verified 


ORepositories 2,241 People 4,321 Projects 0 
Pinned repositories 


vscode TypeScript dotnet 






Visual Studio Code et of JavaScript that 


aScript output. 





@ TypeScript w 68.4k York @ TypeScript w 44.6k Y 6.3k @HT™ML *105k Y17k 
api-guidelines monaco-editor ChakraCore 
Microsoft REST API Guidelines A browser based code editor re is the core part of the Chakra 






cript engine that powers Microsoft Edge 


kosk ¥1.2k @ JavaScript w 13.3k Y11k @ JavaScript %77k Y11k 


Type: All ~ Language: All ~ 


Top | 
vscode-go ‘op languages 


An extension for VS Code which provides support for the Go language eee Corn TA A iai @C# @TypeScript ® JavaScript 








Pinned repositories appear at the top of the Repositories page. Pinned repositories 
are the ones that the Microsoft organization owners think are the most relevant to 
folks interested in what Microsoft is doing in the open source space. For example, 
the VS Code repository has more than 68,000 stars and more than 9,000 forks. As 
one of the most popular editors and most popular open source projects, Microsoft 
wants to make sure this repository is front and center for visitors to their open 
source organization home page. 


Managing members of your organization 


You will always have at least one member of your organization — you! But this 
section is more interesting if you have more than one member, so if you haven’t 
invited other members yet, go to the earlier section “Inviting members to your 
GitHub organization” and invite someone else. 
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To see all your organization’s member, from your organization home page, click 
the People tab. You should see all the members of your organization on this tab, 
as shown in Figure 11-4. 





ue The We Can Zone 


å People 2 Teams 3 


| Members | Outside collaborators 


Repositories 6 Projects 0 Settings 


Invite member 


Select all 1 pending invitation 1 seat left — Buy more 2FA + Role ~ 
Adrian Guthals 
2FA X Ê Private Member 1team Qe 
aguthals 
Manage 
~ Change role... 
ş Sarah Guthals oFAY Private ~ 
FIGURE 11-4: sguthals Convert to outside collaborator 


A list of 
members of an 
organization. 


Remove from organization 








On the right of each member is a small cog drop-down menu. This menu gives you 
quick options for managing your organization members. You can also get all these 
options and more information about a specific member by choosing Manage from 
that drop-down menu. You then see an overview of an organization member, as 
shown in Figure 11-5. 


TIP 





FIGURE 11-5: 

An overview of a 
member of an 
organization. 
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ae The We Can Zone 


Repositories 6 å People 2 


aguthals 
Adrian Guthals 


Role: Member ~ 


Q 6 repositories 
42 1 team 
© Membership private 


A Two-factor security 
disabled 


Convert to outside collaborator 


Remove from organization 





Teams 3 Projects 0 


aguthals has access to 6 repositories 


Ĥ thewecanzone/GitHubForDummies 


Q thewecanzone/test-assignment- 
wecan-student 


¥ thewecanzone/ 
CodingDojo_Presentation 


Bi thewecanzone/swift-playgrounds 


E thewecanzone/ 
thewecanzone.github.io 


H thewecanzone/ 
GitHubForDummiesReaders 


Settings 


Admin on this repository 


Admin on this repository 


Admin on this repository 


Admin on this repository 


Admin on this repository 


Admin on this repository 


Manage access 


Manage access 


Manage access 


Manage access 


Manage access 


Manage access 
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REMEMBER 


Figure 11-5 gives you the following information about the person: 


>> Role: The person's role in the organization with the ability to change it toa 
different role from this page. 


>> Repository access: The number of repositories this person has access to 
within the organization, as well as a list of all the repositories and what 
permissions they have for each one. Each repository has a button that allows 
you to quickly navigate to the settings for that person for that repository. 


>> Number of teams: The number of teams the person is a part of within the 
organization. 


>» Activity: Information on whether the person is choosing to share their activity 
on projects within this organization on their public profile. 


>> Two-factor authentication: Whether this person has two-factor authentica- 
tion enabled for their account. Two-factor authentication can be a require- 
ment of your organization, which you can change in the settings for your 
organization. (See the upcoming section “Setting organization settings.”) 


>> Convert to outside collaborator: A button to convert someone to an outside 
collaborator. This feature is useful for short-term or very scoped projects. 
Instead of having a person be a part of the entire organization, you can make 
them a part of a single team that has access to certain repositories, making 
their privileges easier to manage. 


>> Remove from organization: As straightforward as it sounds. This setting 
removes the person from the organization. 


Creating teams within your organization 


As your organization begins to grow, it may make sense for you to create teams 
within your organization. The benefit of teams is that you can quickly give access 
to a repository to an entire team, without having to remember every single person 
that is on that team. To create a team, click the Team tab on your organization 
home page and click New team. A new page appears where you can choose a team 
name, add a description, choose a parent team (if you’ve created other teams 
already), and set the team’s visibility within the organization. 


Choosing a team name is an important part to consider carefully. The team name 
will be how folks within your organization can tag everyone in the team all at 
once. For example, if you have a security-vulnerabilities team that manages all 
security vulnerabilities for your website “ and a security bug is found, you can tag 
the security-vulnerabilities team, and each person on that team will get a notifi- 
cation. This will help make sure that you get the fastest response time, accounting 
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FIGURE 11-6: 
Creating a 
project board 
linked with 
multiple 
repositories. 


for different time zones, working hours, shifts, and schedules. You want the name 
to be representative of the team because if you had named the team something 
like powerpuffgirls, it would be pretty confusing to see an issue comment that says 


@powerpuffgirls, please review this security vulnerability asap 


creating Teams has a lot more benefits than the ability to mention them all using 
one alias. If you’re interested, read the section “Making the Most of Your Teams,” 
later in this chapter. 


Using project boards within your 
organization 


Chapters 3 and 4 cover how to create project boards and use them when they’re 
associated with a specific repository. By creating an organization, you have 
unlocked the ability to have project boards that link multiple repositories together. 
When you click the Projects tab and click the New project button, to the Create a 
New Project page appears, as shown in Figure 11-6. 





. 
X" The We Can Zone 
Repositories 6 People 2 Teams 3 M Projects o Settings 
Create a new project 
Coordinate, track, and update your work in one place, so projects stay transparent and on schedule. 


Project board name 


2019 Goals 


Description (optional) 


This project board will track 2019 project goals for The We Can Zone. 


Project template 


Save yourself time with a pre-configured project board template. 


Template: Basic kanban ~ 


Linked repositories 


Search thewecanzone to link repositories to this project for more accurate suggestions and better search results. 


Linked repositories: GitHubForDummies x thev 
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TIP 


FIGURE 11-7: 
Settings for 
organization 
project boards. 


Everything is the same about creating the project board as it is when you create 
one for a specific repository (see Chapter 2), except an option at the very bottom, 
right before you click Create project: a section where you can choose which repos- 
itories you want to link to this project board. 


By linking multiple repositories to one project board, any rules you set for specific 
columns (for example, all new issues that get opened in a repository should go in 
a To do column) will apply to all the repositories that are linked to the project 
board. Linking multiple repositories to one project board can help make triaging 
easier for project managers, and give organization leaders a broader picture of 
where the entire organization is, without having to go to each repository to 
check in. 


If you ever need to link more repositories to a project board after you create it, or 
change the visibility of the project or permissions for organization members or 
specific teams, you can click the three dot menu and navigate to the Settings page 
for the specific project board, as shown in Figure 11-7. 





DG The We Can Zone 














Repositories 6 People 2 Teams 3 Mi Projects 1 Settings 
qQ is:open 
M 1 Open v 0 Closed Sort + 
2019 Goals This project board will track 2019 project goals for The We Can Zone. 
© Updated an hour ago 


® Linked repositories: thewecanzone.github.io, GitHubForDummies Edit 


Close 











Setting organization settings 


Organizations have a few more settings than typical individual GitHub accounts. 
On the right-most Settings tab on the organization home page a Settings 
page that is similar to the one we describe in Chapter 1, but with some key 
differences: 


>> Profile is where you can change the organization's name, avatar, and primary 
contact email address or even delete the organization. You can also choose to 
join the GitHub Developers Program (you can read about at https: // 
developer .github.com/program). 
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» 
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Member privileges is where you can set all the default permissions for 

every member in your organization. We recommend changing the default of 
new members from Admin, unless you really want every new member to have 
admin privileges over every repository within the organization. 


Billing is where you can upgrade or downgrade your organization account. 
You can add, change, and remove payment methods, add marketplace apps, 
and add seats within your organization. You can also add billing managers to 
your organization; this can be really useful for folks within your company who 
need to have access to billing information, but may not be savvy or interested 
in the code aspect. 


Security is the area where you can require that all members of your organiza- 
tion have two-factor authentication setup for their GitHub.com account. 


Verified domains is where you can verify a domain that you own so that you 
can verify your organization's identity on GitHub. 


Audit log is a log of all activity done to the organization (not the individual 
repositories part of the organization). 


Webhooks notifies third-party services of events happening within your 
organization. 


Third-party access is all third-party applications that you have given access to 
your repositories. 


Installed GitHub apps is all the GitHub apps that you have installed within 
your organization. 


Repository topics is one place to view and modify the topics for all of your 
repositories. 


Projects contains overall settings for project boards within your organization. 


Teams is where you can enable team discussions, more information about 
this is in the section “Making the Most of Your Teams” later in this chapter. 


Developer Settings has two settings — OAuth Apps and GitHub Apps — and 
a place to specify management of the organization (under GitHub Apps). 


Moderation is where you can block users from your organization or enact 
temporary (24-hour) limitations on what activity can happen on any repository 
within the organization. Figure 11-8 shows that you can block users for short 
periods of time or forever. These moderation settings are often most useful 

in open source project organizations because each member is less likely to 
have a common driving force, such as a paycheck, to behave with respect. 
However, moderation settings can also be useful with inner-source projects 

if things simply start to get heated within the organization. 
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Making the Most of Your Teams 


Having an organization with members grouped into various teams can be useful 
simply for understanding who is doing what, but GitHub provides you with tools 
that make your workflow even more effective when you group organization mem- 
bers into teams. 


Creating parent/child teams 


You can add a team as a parent team to a new team that you’re creating (see the 
section “Creating teams within your organization,” earlier in this chapter). 
Essentially, teams can have hierarchies. The permissions of the parent teams are 
passed down to all child teams, but not vice versa. Hierarchies can become 
extremely useful when you want to ensure that everyone within an organization 
has access to exactly what they need and no more, no less. 


As an example, you may have a team named Employees at the top of your hierar- 
chy. As part of that team, you may have three other teams: Human Resources, 
Marketing, and Engineering. Under the Human Resources team, you may have 
some private project boards or private repositories that only the Human Resources 
team members should be able to see (such as employee personal information). 
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Under the Marketing team, you may have customer data that shouldn’t be shared 
publicly within the organization (such as billing account information). By assign- 
ing all the employees to respective child teams within the organization, you can 
ensure that everyone has access to the employee handbook, while only the folks in 
Human Resources have access to Social Security numbers. 


Discussing teams 


GitHub offers the feature of team discussions when you have an organization with 
teams. Figure 11-9 shows this team discussion home page, which you can find at 
the URL https: //github.com/orgs/ORGNAME/teams/TEAMNAME where ORGNAME 
and TEAMNAME are replaced with the actual names of the organization and team, 
respectively. 


Organization breadcrumbs 


Team alias Team-specific actions 








marks now 





roe [pee reap te 
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Discussions At Members 2 


New Writing Project 
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2 members 


eR + — Looking forward to it! 
| 


child teams 





Member statuses 


MY sauthats Traveling for work 


4» Recent 








There are no discussions for this team yet. 
Start a discussion by typing in the box shove. 
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individual. settings 
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From the team discussion home page, you find 


>> Organization breadcrumbs: On the top left, the hierarchy of this team, all 
the way up to the organization in a clickable breadcrumb-like fashion for easy 
navigation. 


>> Team-specific actions: On the top right, similar menu items that are found 
on repositories and the organization itself, but all will be specific to this team. 


>> Team discussion: In the center right, a place to add new posts to the team 
discussion page. Below this area, you can find previous posts, and you can 
even pin specific posts to stay at the top (useful for important announcements 
or onboarding information). 


>> Team alias: The team alias appears below the team avatar and name on the 
left hand column. You can use this alias to notify everyone in the team about 
something that may be of interest to them, as seen in the team post. 


>> Team members: A list of all team members, a count of how many also belong 
to child teams, and a quick button for adding additional members to the 
team. 


>> Personal notification settings: On the left hand column, a place to quickly 
change your notification settings for this team. 


>> Child teams: A list of all child teams to this team that are linked for quick 
navigation, located on the bottom of the left column. 


Assigning CODEOWNERS 


A really neat feature that GitHub has that is enhanced with the use of teams is the 
CODEOWNERS feature. CODEOWNERS is a way to specify certain people who may 
have the most experience and knowledge on a piece of code. They’re the people 
that, when you’re looking for someone to review your code, you most likely want 
them to take a look. They probably have the most history with the code or are the 
most expert in that domain. By creating teams within your organization, you can 
assign multiple people to be CODEOWNERS of certain code, without having to 
assign each person or keep the list up to date. 


To get CODEOWNERS working on one of your repositories, first make sure that 
you have a team setup that includes members of the organization that should be 
held responsible for ensuring all code that gets added to that repository is correct. 
In our example, I have a team called GitHub For Dummies which includes us two 
authors. On that team page, make sure that you’ve linked the repository that you 
want this team to be CODEOWNERS of and make sure that this team has at least 
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Write access to that repository. Figure 11-10 shows that our team has two reposi- 
tories that we have Write access to: the public one that you can access as a part of 
this book, and a private one that we’re using to track the progress of writing this 
book. We’re going to use CODEOWNERS for the public repository. 





Š The WeCan Zone Writing GitHub For Dummies Discussions 48 Members 1 Teams 0 [Repositories 2 Projects 0 + Settings 


Add repository 


Select all 


thewecanzone/GitHubForDummies pri Write 


FIGURE 11-10: 
Repository 
access for a 
specific team. 


thewecanzone/GitHubForDummiesReaders P Write ~ 











If you give the team only Read access to the repository, then they can’t approve or 

merge a pull request because that is technically writing to the repository. CODE- 

OWNERs (whether individuals or teams) must have either Write or Admin access 
warning to be effective. 


In the repository where you want the CODEOWNERS to be automatically 
added as a reviewer for all pull requests, add a file on the master branch . github/ 
CODEOWNERS with the following code: 


These owners will be the default owners for everything in 
the repo. Unless a later match takes precedence, 
@thewecanzone/github-—for—dummies will be requested for 
review when someone opens a pull request. 
@thewecanzone/github-for—dummies 


* # # # # 


Make sure under the Settings for that repository, you’ve added a branch protec- 
tion to ensure that every time someone tries to make changes to the master branch 
using a pull request, they have to get their code reviewed and approved by at least 
one person and that each pull request requires a CODEOWNER to review and 
approve it. You can set up these requirements in the Branches area of the Settings 
for the repository, as shown in Figure 11-11. 


Now, when you try to add code by opening a pull request, the team @thewecanzone/ 


github-for—dummies will be automatically added to every single pull request, as 
you can see in Figure 11-12. 
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FIGURE 11-11: 
Requiring at least 
one approving 
review from a 
CODEOWNER. 


FIGURE 11-12: 
CODEOWNERS 
automatically 
added to a pull 
request. 
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You can also add specific people or more teams to the CODEOWNERS file by append- 

ing them to the same line. And you can even specify what type of files you want to 

assign to which Code Owners. For a detailed explanation on all of the nuances, you 
TIP can visit https: //help.github.com/articles/about-code-owners. 


Best Practices for Inner-Sourcing 


In Chapters 9 and 10, we describe best practices for both contributing and creating 
your own open source project. Here is the secret: Those best practices all apply to 
inner-sourcing as well. Even if you’re working on your code in private on a small 
team, it is still important to document, follow style guidelines, communicate 
effectively through issues and pull requests, provide applicable feedback through 
thorough code reviews, and be a positive team member. 


When in doubt, pretend the world can see you. 





REMEMBER In addition to following best practices for open source on your private projects, 
you can also leverage additional GitHub resources because your projects are within 
a private organization. 


Repository insights 


When you’re a part of a company, evaluating an engineer on their contributions to 
the team can get tricky. Either as an individual trying to make sure you’re making 
good progress or as a manager trying to write end-of-year reviews and perfor- 
mance ratings, you want to avoid using information to qualify someone’s overall 
contributions and performance. 


That being said, you can get some information to help guide conversations to 
more effectively evaluate yourself or another individual. On a repository, you can 
click the Insights tab at the top right. You see a list of insights about your reposi- 
tory and the people that contribute to it: 


>> Pulse is a snapshot of your repository for a specific time period (defaulted to 
one week). For example, in the month of January, 2019 the Microsoft/VSCode 
project had the following pulse summary: 


Excluding merges, 59 authorshave pushed 1,028 commits to 
master and 1,074 commits to all branches. On master, 1,045 
fileshave changed and there have been28,273additions and 
21,574 deletions. 
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WARNING 


WARNING 


» 


» 


» 


» 


» 


» 


Contributors shows an overall contribution graph for the repository, as well 
as individual contribution graphs for each contributor with a summary of the 
number commits, lines added, and lines removed. 


Tracking contributions to a project simply by lines of code modified or 
number of commits isn’t an effective way to evaluate someone if nothing else 
is taken into account. For example, Shawn could commit every 15 minutes for 
fear of losing work, and Sam could always focus his energies on refactoring, 
making the number of lines of code he changes substantial. Comparing these 
two to Sandra, who had only a few commits and not as many lines of modified 
code but found and fixed a security vulnerability that could have taken down 
the application for good, isn’t a fair comparison. 


Community/Traffic: On public repositories, the community profile on a 
repository helps maintainers understand where they can improve their 
repository to better support their community. You can find out more at 
https: //help.github.com/articles/about-community-profiles— 
for-pub1lic-repositories. On private repositories, the Traffic section gives 
you insight into who is coming to this repository, where they're coming from, 
and what files they're interacting with. 


Commits: This simple commit graph can give you insights into problems your 
repository may have or trends with the lives of your contributors. For 
example, if contributions drop off every year around May, maybe a school 
contributes to your repository a part of the curriculum. And if you typically 
have 300 commits a week but suddenly you start getting only 50 commits, 
maybe folks are running into a problem where they can't get their code 
working well enough to commit. 


Code frequency: Similar to commits, code frequency shows the frequency 
at which lines of code are added and lines of code are deleted. Identifying 
patterns here can help you understand the health of your code as well as 
the profile of your contributors. 


Dependency graph: The dependency graph lists all dependencies (and 
dependents) of this repository and the version it depends on. 


If you want GitHub to create a dependency graph for your private project and 
therefore be able to warn you if you have any dependency security vulnerabilities, 
you have to grant GitHub read-only access to your private repo (see Figure 11-13). 
(For more on dependency security vulnerabilities, read https: //github. 
blog/2@18-07-12-secur ity-vulnerabi 1ity—alerts-for—python/for 

the announcement on security vulnerability alerts for Python.) 


Alerts: On a private repository, you have an Alerts section. If you've enabled 
read-only access to GitHub either via allowing it through the dependency 
graph setting shown in Figure 11-13 or in the Settings tab for the repository in 
the Options category under Data Services, as shown in Figure 11-14, you will 
see security alerts here. 
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FIGURE 11-13: 
GitHub must have 
read access to 
your repository to 
give security 
alerts. 


FIGURE 11-14: 
Allow GitHub 
read access to 
your repository 
for various data 
services. 


>> Network: The network graph shows all the people that have branched and 
forked the repository and any branches of branches or forks of forks. 
Essentially, it shows all the possible states of your repository in the world 
today. Figure 11-15 shows the network graph for the GitHub package for the 
Atom editor. 


>> Forks: The Forks tab lists links to all forks of your repository. 
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FIGURE 11-15: 
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source project. 
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Milestones for larger projects 


Project boards are an effective way to track the progress you’re making through 
the issues and pull requests, but when you’re working as part of a larger organi- 
zation, you will often have larger milestones that you’re trying to reach. GitHub 
provides support for milestones that can be linked to issues and pull requests. 


To create a milestone: 


1. Goto the Issues tab of your repository and click the Milestones button. 


If you don't have a milestone yet, you can click the big, green New milestone 
button on the top right or the big, green Create a Milestone button in the 
center. This will take you to a new page where you can add a title and optional 
due date and optional description. 


2. Click Create milestone. 


You see a list of milestones. 
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In your list of milestones, to the right of the one you just created, is a progress bar 
with a status of the percentage of issues and pull requests completed, the total 
number of issues and pull requests still open, and the total number of issues and 
pull requests already closed. This information can give you a quick snapshot of 
how close you are (or, in most cases, aren’t) to meeting your deadline. 


On your Issues or Pull requests tabs, you can add the milestone to any issue or pull 
request, and the status icon on the milestone list updates automatically. Clicking 
the Milestone gives you a list of all the issues and pull requests associated with 
that particular milestone. 
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Make GitHub 
Work For You 


IN THIS PART... 


Explore ways to keep informed of GitHub repository 
activity outside of GitHub. 


Install popular GitHub integrations into Slack and Trello. 
Set up Octobox to manage GitHub notifications. 


Enhance your editor with GitHub extensions to support 
your collaborative workflow. 


Create a probot app to personalize your GitHub.com 
experience. 


Discover GitHub Actions to customize your GitHub.com 
workflow. 


IN THIS CHAPTER 


» Setting up GitHub integration in Slack 





» Setting up GitHub integrations in 
Trello 


» Installing Octobox to manage 
notifications 


Chapter 12 


Collaborating Outside 
of GitHub 


hile GitHub may be the hub of a software development project (it hosts 

the key deliverable, the source code), it is not the only place where col- 

laboration occurs. Software development teams use a variety of tools to 
communicate and coordinate their software efforts. Many people who are not 
developers also work on a software project and will want to keep apprised of the 
progress of a project in the tools they use. 


For example, a lot of day-to-day collaboration occurs in chat rooms, such as Slack. 
Others may use a Trello board to manage tasks for a team. Still others may use 
Octobox to keep on top of their GitHub notifications. 


In this chapter, we explore the various integrations that bring GitHub information 
into other collaboration tools. This chapter is in contrast to Chapter 13 where we 
cover integrations that bring information from other tools into GitHub to improve 
the software development workflow. 
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Chatting It Up 


212 


TIP 


For many teams, especially distributed teams, chat is a powerful way for members 
of the team to collaborate and coordinate their efforts. Chat in this context does 
not refer to sipping tea on a porch talking about how their day went. Chat refers to 
text-based tools, such as Slack, used by teams to communicate both synchro- 
nously and asynchronously. 


Many teams find it helpful to have GitHub post important notifications into a 
chat room so teams are kept apprised of what’s going on with a repository. In this 
section, we set up a GitHub integration with one popular chat software, Slack. 


Before you install the integration, you need to be the admin of a Slack workspace. 
You can create a free Slack workspace at https: //slack.com. 


After you set up your Slack workspace, installing the GitHub for Slack integration 
requires two key steps: 


1. Install the GitHub app for Slack in the Slack workspace. 
2. Add the Slack App for GitHub to your GitHub account. 


The following sections cover these steps in detail. 


Installing the GitHub app for Slack 


To install the GitHub app for Slack: 


1. Goto https: //slack.github.com and click the Add to Slack button in the 
center of the browser window. 


If you're not logged into your Slack workspace in the browser, clicking the Add 
to Slack button prompts you to sign into your slack workspace. Likewise, if 
you're not logged into GitHub, the site prompts you to log into GitHub. When 
you're authenticated to both, you see a Slack confirmation screen with 
information on what permissions the GitHub app will have to your Slack 
workspace. Figure 12-1 shows the confirmation screen with every section 
expanded (they're collapsed by default), so you can see everything the 
integration can do. 


Be sure you're adding the GitHub app to the correct Slack workspace. If the 
wrong workspace is shown, you can change it by clicking the workspace 
drop-down list on the top right of this screen. Here, you can choose to change 
which Slack workplace you want to install the integration into. If the workspace 
isn’t listed there, you can click Sign in to another workspace. 
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FIGURE 12-1: 
Confirmation 
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2. Click Continue to go to the GitHub app configuration screen. 


As shown in Figure 12-2, this screen prompts you to pick which channels this 
app should be available to. 


3. Choose All Public Channels. 


Any public channel in your Slack workspace can choose to make use of this 
app and subscribe to GitHub repository notifications. 


4. Click the Install button to complete the installation on the Slack side. 


You're redirected back to Slack. 


If you have the Slack desktop application, clicking the Install button attempts to 
launch the application and take you to the workspace where you installed the app. 
If you haven’t yet added the workspace to the desktop application, you’ll just be in 
the last workspace you used. This can be a bit confusing as it may seem like the 
installation didn’t work. Don’t worry, it probably did work. Just add the workspace 
to your desktop application and continue. 
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> = 

GitHub would like to do the following in the 
selected channels: 


Add slash commands and add actions to messages (and 
view related content) 


Post messages as the app 


Select channels 


© All Public Channels 


Any channel accessible to full members of your team 


Specific channels 
Search for channe 


No channels 
FIGURE 12-2: GitHub will still be able to access a private conversation 
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Subscribing to a repository ina 
Slack channel 


After you install the GitHub app for Slack, you can subscribe to notifications for a 
GitHub repository from within a Slack channel: 


1. Type the following command: 
/github subscribe owner/repository 
For example, to subscribe to the repository we created for the readers of this 
book, https: //github.com/thewecanzone/GitHubForDummiesReaders, 
you would type the following in a Slack channel: 
/github subscribe TheWecanZone/GitHubF orDummiesReaders 
The first time you run this command, Slack prompts you to connect your Slack 


account to your GitHub account. as shown in Figure 12-3. This Slackbot 
message is visible only to you. 


214 PART5 Make GitHub Work For You 


FIGURE 12-3: 
Slack message 
with a prompt to 
connect your 
GitHub account. 








a Phil Haack 1:30 PM 
joined #github-for-dummies. 


a Phil Haack 1:30 PM 
set the channel purpose: A slack room for testing out the GitHub app for Slack 


© Only visible to you 


© GitHub APP 1:33 PM 
Finish connecting your GitHub account 


[+ [i 


Today 





Connect GitHub account 








2. 


Click the Connect GitHub Account button to start the process of connect- 
ing your account. 


If you've already authenticated and authorized Slack on GitHub.com by either 
doing these steps previously or by following the steps in the section “Installing 
the GitHub app for Slack,” earlier in this chapter, your browser will open and 
automatically authenticate and redirect you to Slack. 


If you're not authenticated on GitHub.com, GitHub prompts you to authenti- 
cate first and complete the rest of the steps in this section. 


After authenticating, GitHub prompts you to authorize the Slack app, as shown 
in Figure 12-4. You won't need to do this again when installing GitHub into 
other Slack workspaces. 


Click Authorize Slack by GitHub to continue. 


After you authorize the app, GitHub prompts you to choose an org to install 
the app into or to choose your account. 


Click the account name corresponding to the repository you want to 
subscribe to. 


In this example, we are installing to a repository in TheWeCanZone org, so we 
would click that option. Clicking the account takes you to next step where you 
specify which repositories the app may access, as shown in Figure 12-5. 


Choose All repositories to enable the app for all current and future 
repositories or click Only select repositories and pick the specific reposi- 
tories that may use the app. 


After you select the set of repositories, click the Install button to com- 
plete the installation on GitHub. 


Slack is now listed in the Applications page of your account or organization 
settings. You can go there to change the settings for the app or to uninstall it. 
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Slack by GitHub would like access to: 
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Trying out the GitHub Slack integration 


With the installation complete, you can now subscribe to GitHub repositories in 
your Slack channels. To see the full list of Slack commands, type the following: 


/github help 


The output of this command is shown in Figure 12-6. 





© Only visible to you 
GitHub APP 2:01 PM 
wy Need some help with /github ? 
Subscribe to notifications for a repository: 
/github subscribe owner/repository 


Unsubscribe from notifications for a repository: 
/github unsubscribe owner/repository 
Subscribe to notifications for all repositories in an organization: 


/github subscribe owner 


Unsubscribe from notifications for an organization: 
/github unsubscribe owner 


List all active subscriptions in a channel: 
/github subscribe list 


Close an issue: 
/github close [issue Link] 


Reopen an Issue: 
/github reopen [issue link] 


Adjust your settings in this workspace: 
/github settings 


Connect your GitHub account: 
/github signin 


Show this help message: 


FIGURE 12-6: Fathi help 








Summary of aes ; 
š A reate a new issue: 
available GitHub : - 
/github open owner/repository 
commands 
C) Learn More — Contact Support 
on Slack. 





To test the GitHub app and open a new issue: 
1. Runthe following command. 
/github open TheWeCanZone/GitHubForDummiesReaders 


A Slack dialog box appears. You can use this dialog box to create a new issue, 
as shown in Figure 12-7. 
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FIGURE 12-7: 
Slack dialog to 
create an issue 
on GitHub. 


FIGURE 12-8: 
Slack message 
with information 
about a newly 
created GitHub 
issue. 


TIP 





QO Open a new issue 
Repository 


thewecanzone/GitHubForDummiesReaders, 





Title 





Using Slack to create an issue 


Body 





Just testing the GitHub for Slack app 





P 
GitHub markdown syntax is supported, although you cannot preview it in Slack. 


Label (optional) 











good first issue 


© Learn more about GitHub 


2. Fillinthe dialog box and click the Open button. 


Clicking the Open button creates the issue on GitHub. And because we're 
subscribed to that repository, we get a Slack message in the channel that the 
issue was created as shown in Figure 12-8. 





| Subscribed to thewecanzone/GitHubForDummiesReaders 


GitHub APP 1:56 PM 
Issue opened by Haacked 
Ø Haacked 
#7 Using Slack to create an issue 
Just testing the GitHub for Slack app 
Labels 
good first issue 
© thewecanzone/GitHubForDummiesReaders Today at 1:56 PM 








[+] Message #github-for-dummies 


If you find a bug with the GitHub integration or have an idea for a way it could be 
better, good news! It’s open source on, of course, GitHub! You can log issues or 
even contribute at https: //github.com/integrations/slack. 
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The /github subscribe command by default subscribes a channel to notifica- 
tions for the following features of a repository: 


>> issues: Opened or closed issues 

>> pulls: New or merged pull requests 

>> statuses: Statuses on pull requests 

>> commits: New commits on the default branch (usually master) 
22 deployments: Updated status on deployments 

>> public: A repository switching from private to public 


>> releases: Published releases 


To subscribe to only a single feature, use the /github subscribe owner/repo 
[feature] command. 


/github subscribe TheWeCanZone/GitHubForDummiesReaders reviews 
You can remove a single feature by using the /github unsubscribe owner/repo 
[ feature] command. For example, to remove commit notifications on the default 
branch, run the following command. 


/github unsubscribe TheWeCanZone/GitHubForDummiesReaders commits 


Additional features are disabled by default: 


>> reviews: Pull request reviews 
>> comments: New comments on issues and pull requests 
>» branches: Created or deleted branches 


>> commits:al1: All commits pushed to any branch 


Getting Trello and GitHub Integrated 


Trello is a collaboration tool used to organize projects into boards, lists, and cards. 
It’s inspired by the Kanban scheduling system popularized by Toyota. Kanban is 
Japanese for signboard. The idea is to have a board that provides a view of a proj- 
ect’s status and progress at a glance. 


CHAPTER 12 Collaborating Outside of GitHub 219 


220 


TIP 


TIP 


TIP 


Often, a tool like Trello is combined with GitHub to manage a project. A project 
team may use Trello to manage the entire project, but use GitHub to host the code 
and assign specific code issues to developers. A card in Trello might correspond to 
multiple GitHub issues. 


GitHub Project Boards are essentially Trello with GitHub already integrated into 
it. However, Project Boards within GitHub aren’t always the right fit for your 
team. Some teams have nondeveloper folks who don’t want to have to learn 
GitHub and may already be using Trello. Typically, it’s best to have all your proj- 
ect management in one place, so if that should be outside of GitHub, in Trello for 
example, you can still make it a part of your developer workflow with this 
integration. 


A GitHub integration (what Trello calls a power-up) for Trello connects cards to 
GitHub issues, pull requests, and branches. In the next section, we walk through 
setting up the GitHub power-up. 


Installing the GitHub power-up 


The following installation instructions assume that you’ve already signed up for 
https: //trello.com and created a project board: 


If you’ve never used Trello, you can visit its guides at https: //trello.com/ 
en-US/guide. It is similar to GitHub Project Boards (see Chapter 3). For specific 
help on creating a board and cards, visit https: //trello.com/guide/create- 
a-board.html. 
1. With a board open, make sure the menu is open. 

If not, click in the top right to show the menu. 
2. Click the Power-Ups section of the menu, as shown in Figure 12-9. 

Clicking the Power-Ups button brings up a search dialog box for power-ups. 
3. Search for GitHub to find GitHub related power-ups. 
4. Click the Add button for the GitHub power-up to enable it. 


Just like for any application, Trello may have GitHub power-ups (extensions/ 
integrations) that are built by GitHub and some that are built by other folks. 
Since GitHub’s API is public, folks can often create power-ups/extensions of 
their own. Be sure you're always aware of the author of the power-up/ 
extension when you're installing it. You may very well want to install from a 
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third-party developer instead of GitHub itself because the features might be 
different. Regardless, you should make sure you're aware of that choice. Don't 
assume anything with “GitHub” in the title is made by GitHub the company. 


Power-Ups 


© ®® (T GitHub for Readers | Trello x + 
€ > © @ https://trello.com/b/G8a4dcxd/github-for-readers 


A @ Boards o 


GitHub for Readers “ Haack Family “Free & Team Visible Menu 


& Share 
OB change Background 
Da Y Filter Cards 
+4 © Stickers 





<] Power-Ups 
Calendar, Google Drive and more... | 


Add Power-Up... 





‘= Activity 
FIGURE 12-9: Phil Haack added Done to this board 
Power-Ups emia. ede 
section of the 7 : : J 
menu. https://trello.com/b/G8a4dcxd/github-for-readers# & Lu Haak added Doing to this board 








5. after you enable the power-up, click the gear icon in the corner to 
configure it. 


You see a menu with the option to disable the power-up, or authorize it. 
6. Click Authorize Account. 

An option to link your GitHub account appears. 
7. Click Link Your GitHub Account. 


GitHub.com launches in your browser and prompts you to Authorize Trello, as 
shown in Figure 12-10. 


Before clicking the Authorize trello button, make sure to click the Grant button 
next to any organizations that you want to connect with Trello. In my case, I'll 
grant Trello access to the thewecanzone organization and then click the 
Authorize trello button to make the power-up active. 
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eee Authorize application 
â GitHub, Inc. [US] | https://github.com/login/oauth/authoriz 


w oc) 


Authorize Trello GitHub Integration 





response_type= 


Trello GitHub Integration by trello 
wants to access your Haacked account 


Repositories 


v 
Public and private 
a Organizations and teams v 
Read-only access 
Organization access 
2 dotnetfringe v 
Ø eme v 
@ dotnet x Request 
‘Ø Nucet x Request 
| aspinsiders x Grant 
Š thewecanzone v Revoke 
EÈ haacked-demos x Grant 
FIGURE 12-10 Authorize trello 
. Authorizing will redirect to 
Authorize Trello https://github.trello.services 








on GitHub. 


Using the GitHub power-up 


The GitHub power-up is accessed via the power-up button on the back of any 
Trello card. If you haven’t already, go ahead and create a couple of cards. 


To use the GitHub power-up on your Trello board, follow these steps: 


1 e Click the card to access the back of the card. 


Figure 12-11 shows a card that we created. The GitHub power-up shows up in 
the bottom right corner. 


2. Click the GitHub Power-Up button. 


Four menu options appear: 


Attach Branch 


e 


Attach Commit 


e 


Attach Issue 


e 


Attach Pull Request 
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D 


€ 





FIGURE 12-11: 
Trello card with a 
GitHub power-up. 


Aaw 


Demonstrate the Trello GitHub integration 


in list Todo 


Description 


Add a more detailed description... 


ES < 
Add Comment 


Write a comment... 


Formatting help 





ADD TO CARD 


& Members 


© Labels 


© Checklist 


© Due Date 


@ Attachment 


POWER-UPS 
© GitHub 


Get More Power-Ups 









GitHub power-up 


Click Attach Issue to bring up a repository search dialog box. 


Find the repository that contains the issue you want to attach to the card. 


After you select the repository, you see a list of issues, as shown in Figure 12-12. 


You can also search for issues. 


Clicking the issue from the drop-down list attaches it to the Trello card. After 
you attach the issue, the issue is displayed on the back of the Trello card. 





@ © @ GD Demonstrate the Trello GitHub x 


€ 


FIGURE 12-12: 
Selecting the 
issue to attach. 





$ 
Cc 


© Add Comment 


G Write a comment... 


Activity 


eS Phil Haack added this card to Todo 
= 6 minutes ago 


@ @ © B 


@ https://trello.com/c/E3QERMy6/1-demonstrate-the-trello-github-integration# 


&% Checklist 


© Due Date 


© Attachment 


POWER-UPS 






& Issues from thewecanzone/GitH... X 


Search issues. 


#8 Attach a GitHub Issue to a Trello card 
#7 Using Slack to create an issue 


Choose a different repo... 


© Watch 


5 Archive 


< Share 
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FIGURE 12-13: 
Trello card with 


an issue and pull 


request attached. 


FIGURE 12-14: 
Front of a card 
with an issue and 


224 


pull request 
attached. 





A Trello card may be attached to multiple GitHub items. For example, repeat the 
previous steps, but choose Attach Pull Request instead of Attach Issue to attach a 
pull request to an issue. When you are done, you see both an issue and a pull 
request attached to the Trello card, as shown in Figure 12-13. 











& Demonstrate the Trello GitHub integration x 
in list Doing 
= Description ADD TO'GARD 
& Members 
Add a more detailed description... 
© Labels 
© Checklist 
© GitHub Pull Requests Remove... 
© Due Date 
nu README.m: pi 
thewecanzone/GitHubForDummiesReaders #5 opened by sguthals 
merge sguthals-patch-2 into master © Attachment 
POWER-UPS 
itHub l: Remove... 
© GitHub Issues Slane 
© Attach a GitHub Issue to a Trello card L 
thewecanzone/GitHubForDummiesReaders #8 opened by Haacked Get More Power-Ups 


Status: open 





The front of the card shows a couple icons that indicate that this card is attached 
to GitHub. It shows an Octocat icon with a count of GitHub items attached to the 
card. It also shows pull request icon with a count to indicate the number of pull 
requests attached, as shown in Figure 12-14. 


A [M Boards o) 


GitHub for Readers z — Haack Family ‘Free & Team Visible 


Todo coo Doing 


+ Add a card Demonstrate the Trello GitHub 
integration 


@2 2 fh1 


+ Add another card 
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When you visit the issue or pull request on GitHub.com, you can see that the 
attachment is bidirectional. The GitHub issue now has a link to the trello card, as 
shown in Figure 12-15. 





a Haacked commented a minute ago Member 


| want to demonstrate the integration of Trello and GitHub. 








FIGURE 12-15: ey Haacked commented 25 seconds ago Member 
GitHub issue 
with a link to the Œ Demonstrate the Trello GitHub integration 
Trello board. 





Managing Notifications with Octobox 


Earlier in this chapter, we cover a couple of integrations that bring GitHub infor- 
mation into other collaboration tools. GitHub integrations help teams work 
together. 


In this section, we cover a GitHub app that’s a little different. It’s a tool to help 
individuals manage the flow of GitHub notifications. As you participate in more 
and more GitHub repositories, the number of notifications can start to get over- 
whelming. Octobox provides an email client style view of your notifications. 


Installing Octobox is pretty straightforward: 


1. Goto https: //octobox.io and scroll down to the button labeled Install 
the GitHub App. 


Some pricing options appear, as shown in Figure 12-16. Octobox is free for 
open source projects. 


N 


Click Install it for free to continue with the installation process. 
3. Authorize the application the same way you authorized Slack and Trello, 


earlier in this chapter. 


After the installation and authorization steps are complete, you’re taken to your 
Octobox inbox. The first time it runs, it takes a moment to synchronize your noti- 
fications. When it’s done, you should see something like Figure 12-17. 
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FIGURE 12-16: 
GitHub app 
download button 
and Pricing 
options for 
Octobox. 


FIGURE 12-17: 
Octobox inbox 
for the author. 


226 





Liven up notifications with the GitHub app 


By default Octobox will pull basic public and private notification information: 


TA #1264 Increase time inbetween automatic syncing of users (2 


Install the GitHub app to add live information on issue, PR, and CI status, labels, authors and more to 


your organisation's notifications: 


T) #1263 Add index on github_id for repositories table 


Install the lub App i 


Pricing 


Octobox is free for open source projects with basic notifications for private projects. To add 
enhanced notifications for private repositories to your organisation's account: 


Open Collective 


Support the community 


Pay by donation on Open Collective. 


Private repository access 


v Unlimited private repositories 
v Unlimited public repositories 
¥ Unlimited collaborators 


trom $10 user / month 





GitHub Marketplace 


Support the company 

Buy from the GitHub marketplace. 
Private repository access 

v Unlimited private repositories 


v Unlimited public repositories 
¥ Unlimited collaborators 


from $10 /user / month 








Donate on Open Collective 


Subscribe on GitHub 


lective Next: confirm your purchase on GitHub 





Next: make your donation on Ope 


Wondering why there are two options? Read more about our pricing strategy. 




















@ Oe a octobox x + 
€ Œ à https://octobox.io/?unread=true t 9 
© Private Notification Changes 
Lest sync: 7 minutes ago 
at ee | © #78 Setup gpg signing C (ERED desktop/desktop joshaber 239 Feba 
w& Starred 
#214 Repositority description contains link without SSL semver/semverorg hartwork D1 Jan29 
= A 
3 Pin this search = 
®© #490 Clarify points 4 and 5 in Semver 2.0 [3 semverjsemver ajbogh [Subscribed | po Jan29 
f #21 Ease development using docker-compose [3 semver/semver.org hartwork a2 Jan29 
a ®© #482Sadcss?[4 semver/semver hartwork IEEE) os anze 
a 
© #114 Looking for New Maintainers [2 ithub/Scientist.net “Mention Jan 26 
a 
@ _ #215 What is the next version number if i do a semver/semver “Mention: Jan 25 
© Unlabelled s refactoring or a documentation update only? (2 
‘> Commit s © #7 Doesn't work as expected [7 damieng/iekyll-biog-COm =I Jan 25 
@® Issue 151 
#489 Human-readable spec should specify decimal semver/semver [subscribed J Jan 24 
Ti Pull request 4 ® = 
integers 3 
A Vulnerability alert 
#112 Scientist.net.git (4 cithub/Scientist.net ‘Mention’ Jan 21 
@ Assign 1 
#484 Decrement is undefined (7 semver/semver [ Subscribed ] jan 21 
@ Author 5 © a mver/semve i 











After Octobox is installed and synchronized, you can use it to manage your noti- 
fications. It allows you to search and filter your notifications by repository, orga- 
nization, type, action, status, and so on. You can set Octobox to automatically 
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synchronize on an interval in its Settings page. As the status for issues and pull 
requests change on GitHub, synchronizing Octobox displays those changes in 
Octobox. Octobox also provides archiving and muting for notifications, which is a 
nice way of staying on top of notifications, especially if you work on multiple 
active projects on GitHub. 


In this chapter, we note that people collaborate on a project in many places other 
than GitHub. For example, people may use Slack to chat about a project and Trello 
to manage tasks for a project. The GitHub apps for these two products pull infor- 
mation from GitHub into these spaces. This is useful for those who are not on 
GitHub as the apps may provide important context. It also helps reduce context 
switching as folks may not need to constantly switch back and forth from their 
app and GitHub. 


The last app, Octobox, serves a different purpose. It is a tool that fills in a gap in 
the GitHub product and makes GitHub notifications more manageable. These are 
just three examples of the many apps that make it possible to collaborate on 
GitHub in contexts outside of GitHub. 
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IN THIS CHAPTER 


» Exploring GitHub Integrations 





» Using GitHub Integrations 


» Keeping informed about GitHub 
Integrations 


Chapter 13 


GitHub Workflow 
Integrations 


n Chapter 12, we show you some ways that you can get information about 

GitHub repos in other applications. Using applications like Slack and Trello, 

integrated with GitHub, can especially help you with project management. In 
this chapter, we show you some ways you can integrate GitHub into your existing 
development workflow. 


A lot of the integrations that we show you in this chapter are open source, which 
means you can track the development of new features, easily report bugs through 
GitHub, or even contribute to the project. It also means that each is rapidly chang- 
ing, so some details may be outdated by the time you read it. What is important is 
that you know how to find updates and navigate each integration. 


Using GitHub for Atom 


Atom is a lightweight, open source editor, so you can track the progress and report 
issues directly on the GitHub repo where it’s being developed. Atom has both a 
GitHub and Git integration that can help improve your development workflow 
when collaborating with others. 
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FIGURE 13-1: 
The GitHub tab 
when no project 
is open in Atom. 


To get started, make sure you’ve downloaded Atom from https: //atom. io. Then, 
open the GitHub tab in one of the following ways: 


>> Choose Packages ™ GitHub and then select the Toggle GitHub tab 
>> Click the GitHub button at the bottom right of the Atom window 


>> Use the keyboard shortcut Ctrl+Shift+8. 


Viewing, checking out, and creating 
pull requests 


When you first open the GitHub tab, what you see depends on the state of the 
repository that you have open in Atom. Figure 13-1 shows what happens if you 
don’t have a repository open in Atom at all. The blank screen isn’t an error; there 
is just no project, so the GitHub tab has no actionable items or feedback for you. 





@ Atom File Edit View Selection Find Packages Window Help 
eee untitled 











“A? (GitHub ©Git (0) 





If you have a project open in Atom that isn’t associated with a GitHub repository, 
then you see the same blank tab that is shown in Figure 13-1. If the project is only 
a local project (for example, you created the repository using git init or it’s just 
a folder on your computer, but you don’t have it backed up to any hosting platform 
like GitHub), you also have a notification at the bottom of the Atom window that 
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FIGURE 13-2: 

The GitHub tab 
when a GitHub 
project is open in 
Atom, but you 
have not yet 
authenticated 
with GitHub. 


indicates that no remote repository exists for this project. If the project is hosted 
somewhere other than GitHub, such as GitLab, you still see a blank tab like in 
Figure 13-1, but the bottom of the Atom window has the button for fetching, 
pushing, and pulling your code. This button is a feature of the Git integration and 
isn’t specific to GitHub. 


Figure 13-2 shows the login button that you see if you have a GitHub repo open in 
Atom. When you click the Login button, you’re asked to go to http: //github. 
atom.io/login to generate an authentication token to paste into the Atom 
window. 





@ Atom File Edit View Selection Find Packages Window Help 





eee GitHub — ~/Downloads/GitHubForDummiesReaders 
Project © Git x BB GitHub x 
v © GitHubForoummiesReaders 
> fi github 
B License 


README.md 


Log in to GitHub 


Log in to GitHub to access PR information and 
more! 





tA B master GFetch ()GitHub Git (0) 





After you give permission to the GitHub package for Atom to access your account, 
you’re given a long authorization token. After you paste that token into Atom, you 
see a list of all the open pull requests on that repository and information about 
which branch you’re on (see Figure 13-3). 


You can check out a branch associated with a pull request by clicking the pull 
request and then clicking the blue Checkout button, as shown in Figure 13-4. 


Notice that in Figure 13-4, multiple tabs at the top of the detailed pull request view 
allow you to check the build status, view the list of commits on this branch, and 
view the diff of the files that were changed compared to the target branch for this 
pull request. 
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@ Atom File Edit View Selection Find Packages Window Help 





eee GitHub — ~/Downloads/GitHubForDummiesReaders 
Project Git x @ GitHub x 
v [H GitHubForDummiesReaders * Checked out pull request 
>a You are currently on your repository's default branch. 
> B github 


B Checkout or create a new branch to share your work with a pull 
B ucense oaia 


EE README.md 
¥ Open pull requests 
FA Testing CoDEOWNERS ~ 
EN Update README. md ~ 
EN Adding myself to the table 


> FBR create neverAddMe.md - 


FIGURE 13-3: 
The GitHub tab 
showing all open 
pull requests on 
that repository. 


t D master SFetch Ocithub Git (0) 
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esoe PR: thewecanzone/GitHubForDummiesReaders#6 — Testing CODEOWNERS — ~/Downloads/GitHubForDummiesReaders 





Project PR: thewecanzone/GitHubF... x Git xo @B GitHub x 


M E GitHubForDummiesReaders * Checked out pull request 
QO 
Testing CODEOWNERS 








> BB github master < sguthals-patch-3 
Ry Leis P Checkout or create a new branch to share your work with a pull 
B) ucen 
recast 
Eo ® $ Build Status Commits 1 Files 1 
¥ Open pull requests 
This is a pull request to test CODEOWNERS. E Testing concowners 
EN Update README.ma 
FER update reaome.ms osbbare? BM Adding myself to the table 
E create noveradate.md = 
> 
The detailed view 
of a pull request 
with the Checkout o 
button PR: thewecanzone/GitHubForDummiesReaders#6 — Testing CODEOWNERS 0A’ B master GFetch ()GitHub ©Git(0) 





When yov’re on a branch associated with a pull request, that pull request will be 
brought to the top of the GitHub tab, as shown in Figure 13-5. 


If you create or check out a branch that isn’t yet associated with a pull request, the 
GitHub tab adds a Publish button to the top section, above the list of open pull 
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FIGURE 13-5: 
The GitHub tab 
showing the 
current pull 
request at 

the top. 


requests. Clicking this button publishes your branch and then takes you to the 
GitHub.com web page where you can create a pull request for that branch. This 
button replaces the Testing CODEOWNERS pull request in the Checked out pull 
requests section in Figure 13-5. 





@ Atom File Edit View Selection Find Packages Window Help 
eco ~/Downloads/GitHubForDummiesReaders 
Project Git x o GB GitHub x 
~ DB GitHubForDummiesReaders Checked out pull request 


EN Testing coneowners 
> B github 


B ucense 


Open pull requests 
E Testing covcownens 
EF README.md 
EN Vodite README ma 
EN Adding myseif to the table 


E croato novoradame.ma 








tA? I pr-6/thewecanzone/sguthals-patch-3 GFetch ()GitHub  ©Git (0) 





Viewing issues 


You can also view issues in Atom using a nifty Command Palette command. First, 
open the command palette by choosing Packages > Command Palette or by press- 
ing 3¢+Shift+P. From there, start typing GitHub: Open, and you should find the 
GitHub: Open Issue or Pull Request option, as shown in Figure 13-6. Choose that 
option. 


Paste in the URL to any issue (this work for pull requests also) and click the Open 
Issue or Pull Request button, and the issue details open in Atom with all the com- 
ments, just like on GitHub.com (see Figure 13-7). 


You can’t interact with issues other than reading them, but viewing issues in 
Atom can still be useful if you need to reference an issue while you’re working on 
some code. With the open issue feature, you don’t have to have a browser window 
also open and continuously toggle between the browser and Atom. 
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FIGURE 13-6: 
The GitHub tab 
showing the 
current pull 
request at 

the top. 


FIGURE 13-7: 
GitHub issue 
details opened 
in Atom. 
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@ Atom File Edit 


View Selection Find Packages Window Help 








eso 
Project 
v E GitHubForDummiesReaders 
> Mok 
> Ba github 
B ucense 





GitHub — ~/Downloads/GitHubForDummiesReaders 


READ! | Github: op! 
1 # 
2 T| | GitHub: Open Commit 
* D| | GitHub: Force Push 
w Pp 
3 GitHub: Open Issue Or Pull Request 
4 S| | GitHub: Toggle Commit Preview 
- yl 


GitHub: Close Empty Diff Views 





J -aa 


8 @sguthals 
@haacked 


| I have a dog and two cats! 
| I love formatting markdown. 


l 
5 GitHub x 


joked out puli request 


pull requests 


xG oP 





bsting CODEOWNERS ~- 12 


pdate README.md 





Hiding myself to the 





| 
‘raw-vfeate neverAddMe.md n-m 





README.md 10:1 


LF UTF-8 GitHub Markdown "A? ẸỌ MyOtherNewBranch OFetch 


(GitHub _ oir (0) 
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eco 
Project 
~ E GitHubForDummiesReaders 
> Mg 
> Ml github 
B ucense 


- Issue: thewecanzone/GitHubForDummiesReaders#7 — Using Slack to create an issue — ~/Downloads/GitHubForDummiesReaders 


README.md x Issue: thewecanzone/GitHu... 


Using Slack to create an issue 


bForDummiasRe: 





Just testing the GitHub for Slack app 





jays ago 


create an issue in GitHub or slack? Why not both? 


mnmente 





© GitHub x 


¥ Checked out pull request 


* Open pull requests 








F Testing CODEOWNERS We — 12% 
EN Update README.ma s-r 


FEN Adding myself to the table s- 


FA create neverAddMe.md n- 





C) thowscanzone/GitHubForDummiesReaderss7 





Issue: thewecanzone/GitHubForDummiesReaders#7 — Using Slack to create an issue 
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UR? P MyOtherNewBranch GFetch C)citHub  ->Git (0) 





Following the GitHub package for Atom 


The GitHub package for Atom has extensive documentation, which you can find in 
the Atom Flight Manual at https://flight-manual .atom.io/using-atom/ 
sections/github-package. Here you find a list of all the Git and GitHub features 
with screenshots and in-depth descriptions. 


You can also track the progress of new or future features on the GitHub repo itself 
at https: //github.com/atom/github. The GitHub package for Atom team often 
uses project boards, issues, pull requests, and RFCs (request for comments) to 
plan, design, and implement new features. For example, you can find the RFC for 
the pull request review features at https: //github.com/atom/github/blob/ 
master /docs/ feature-requests/@Q@3-pul 1—-request-review.md. 


Using GitHub for Visual Studio Code 


WARNING 


One of the fastest growing editors is Visual Studio Code (VS Code for short). With 
more than 2.6 million active users in the first 12 months in 2017, you have probably 
either used it or at least heard about it. Like Atom, VS Code is open source, which 
means you can see the development of new editor features at https: //github. 
com/microsoft/vscode. In 2018, Microsoft and GitHub teamed up to build an open 
source GitHub editor extension that provides an in-editor pull request experience. 


After you install VS Code, you can install this extension by going to the extension 
marketplace, searching for GitHub, and clicking the green install button for the 
GitHub Pull Requests extension, as shown in Figure 13-8. 


You have to reload the VS Code window after you install the extension. Reloading 
should take only a couple of seconds, and if you have any projects already open, it 
shouldn’t be a problem. 


After you install the extension, you can sign in to GitHub. You can sign in to 
GitHub in three ways (see Figure 13-9): 


>> Click the Octocat button at the bottom left of the VS Code window. 


>» Click the notification at the bottom right of the VS Code window. 


>» Use the Command Palette, which you can open by pressing $g+Shift+p and 
searching for the sign in by typing GitHub. 


The sign-in process opens a web browser where you can authorize VS Code to 
access your GitHub repositories. Click through the prompts, and it redirects you 
back to VS Code. After you’ re back in VS Code, you get a pop-up notification asking 
whether you trust the URL; click Yes. 
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GitHub extension 
for VS Code in the 


marketplace. 
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l Review and manage your GitHub pull requests directly in VS Code 


This extension allows you to review and manage GitHub pull requests in Visual Studio Code. The 
support includes: 


Authenticating and connecting VS Code to GitHub. 

Listing and browsing PRs from within VS Code. 

Reviewing PRs from within VS Code with in-editor commenting. 
Validating PRs from within VS Code with easy checkouts. 
Terminal integration that enables UI and CLIs to co-exist. 
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GitHub Pull Requests: Sign in to GitHub 

GitHub Pull Requests: Manually Provide Authentication Response 
x 4) Release Notes: 1.3 GitHub Pull Requests: Refresh Pull Requests List 

4 GITHUBFORDUMMIESREA! Source Control: Focus on GitHub Pull Requests View 


Release Notes: 1.32.0-insider — GitHubForDummiesReaders 


recently used 
other commands 


Insiders Release 


Welcome to the Insiders build. These are the preliminary notes for the February 1.32 release of Visual 
Studio Code. As we get closer to the release date, you'll see details below about new features and 
important fixes. 


Until the February release notes are available, you can still track our progress: 


* February Iteration Plan - See what's planned for the milestone. 
* Commit Log - GitHub commits to the vscode open source repository. 
+ Closed issues - Resolved bugs and implemented feature requests in the February milestone. 


We really appreciate people taking a look at our new features as soon as they are ready so check back 
here often and learn what's new to try out. 


If you find issues or have suggestions, you can enter them in the VS Code repository on GitHub. 


Thank you 


Last but certainly not least, a big Thank You! to the following folks that helped to make VS Code even 


better: 
a NOTIFICATIONS Y 
Contributions to vscode-Langué 
@ In order to use the Pull Requests functionality, youneedto # x 


+ Aleksey Kladov (@matklad): 
sign in to github.com 


Source: GitHub Pull Requests (Extension) 








@0 40 C) Signin to github.com 


Interacting with pull requests in VS Code 


After you’re signed in, when you go to the Source Control tab on the left side of VS 
Code, you should see all the pull requests associated with this repo. Pull requests 
are grouped into five different sections: 


>> Ones that you currently have checked out 
>> Ones where you are marked as a reviewer 
>> Ones that you're assigned to 


>> Ones that you created 


>> A list of all pull requests 


When you unroll a specific pull request, you see the description of the pull request, 
along with all the modified files. 


Clicking the description of the pull request displays the description as you would 
see it on GitHub, as shown in Figure 13-10. From this page, you can check out the 
pull request, leave a comment, merge or update the pull request, or complete a 
review. You have the entire pull request experience right inside of VS Code! 
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FIGURE 13-11: 
Adding an inline 
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comment in 
VS Code. 


Another feature of this extension is the ability to add inline comments to the diff. 
Clicking a specific modified file shows you the side-by-side diff, just as it would 
look on GitHub.com. From here, you can add a comment to any of the modified 
lines, as shown in Figure 13-11. All these actions are reflected on GitHub.com. 
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Following the GitHub for VS Code pull 
requests extension 


Because this extension is also open source, you can follow the development, 
report issues, or even contribute to it on GitHub.com. Go to https: //github.com/ 
Microsoft/vscode-pul1l-request-github to find the latest features and docu- 
mentation for how to use this extension to improve your development workflow. 


The VS Code and GitHub teams working on this extension often use a tracking 
issue to track what they’re working on. You can find the most recent iteration plan 
for this project by going to the Issues tab on the GitHub repo and filtering the 
issues by the label iteration-plan. 
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Using GitHub for Unity 


Unity is a cross-platform game engine that game developers use to build scenes 
and attach code scripts to games. You can write the code in any editor you want, 
or you can use MonoDevelop, the editor that is shipped with Unity. 


Integrated development environments (IDE), such as Visual Studio, have integra- 
tions that make writing code for your Unity game a better experience. With the 
full-featured experience of an IDE coupled with a clean connection back to Unity, 

TIP you can be an even more effective game developer! After you create a new project 
in Unity, you can add the GitHub extension to your project. Unity is different from 
other editors. In Unity, every extension is represented as an Asset and is a part of 
your game, not a part of the development environment. So, when you add the 
GitHub extension to your Unity project, the files for that extension are a part of 
your game. Don’t worry; they won’t appear in your finished game, but they will 
help while you’re collaboratively building it! 


First, open the Asset Store in Unity by choosing Window™ Asset Store. Search 
GitHub, and you will find the GitHub for Unity asset, as shown in Figure 13-12. It 
is free. 
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FIGURE 13-12: 
| 
in the Asset Store. 
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FIGURE 13-13: 
Installing the 


GitHub for Unity 
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extension. 


Click the GitHub for Unity asset, scroll down, and click the big pink Import button. 
A pop-up window with all the files that will be added to your project appears, as 
shown in Figure 13-13. Click Import. 
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Using GitHub for Unity in Unity 


After you install the extension, you see a new menu item in the Window menu 
called GitHub. If you choose GitHub, a new tab opens in Unity (see in the back- 
ground of Figure 13-14). Click the Initialize a git repository for this project button 
in the center of the new tab, and the GitHub tab updates with additional tabs 
related to git actions. At the top right of the GitHub tab, you can click the Sign in 
button to sign in to your GitHub account, shown in Figure 13-14. If you have 
two-factor authentication setup, you are asked for your 2fa code. 


When you’re ready, you can publish your project to GitHub by clicking the Publish 
button at the top left of the GitHub tab. In the Publish dialog box, shown in 
Figure 13-15, choose which GitHub organization should own this project, put in a 
repository name, add a description, and choose to make it public or private. 
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FIGURE 13-14: 
Signing in 
to GitHub 

inside of Unity. 


FIGURE 13-15: 
Publishing your 
project to 
GitHub.com. 
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After the project is published, you can continue to work on your project just like 
you would any other coding project. Items that you may find useful include 


» 


» 


» 
» 


» 


» 


» 


Changes where all the recent changes are listed. You can add changes to a 
commit and then commit them to the branch that you're on. 


Locks where you can lock certain files and assets so that only you can modify 
them. This lock becomes extremely important if you're making changes to a 
game scene and you don't want someone else to also make changes to that 
scene and overwrite your work. 


History is a history of all the commits for this project. 


Branches where you can see all the branches on this repo, create a new 
branch, and switch branches. 


Settings where you can change the remote path of your repository, change 
the path to git that this extension is using, and even update your git username 
or email. It's recommended that you don't modify these settings unless you 
know what you are doing. The extension will set these up properly for you. 


Fetch/Pull/Push/Refresh is at the top of the GitHub tab and contains four 
buttons that sync your GitHub repo with your local project. 


GitHub Username is at the top right of the GitHub tab where you see your 
username and go to your GitHub.com profile or sign out of GitHub inside of 


Unity. 


Following the GitHub for Unity extension 


The GitHub for Unity extension is open source, so you can track development, 
report issues, or even contribute to it via the GitHub repo at https: //github. 
com/github-for-unity/Unity. It’s also important to always keep the extension 
up to date. A pop-up window appears in Unity whenever a new version is released, 
but you can also check on the Unity Asset store or directly download the latest 
version all from https: //unity.github.com. 


The team working on this extension is fairly small, so if you’re interested in con- 
tributing to the project, we’d highly encourage you to give it a go! You can always 
check out the issues on the repo on GitHub.com for ones labeled Help Wanted or 
Good First Issue. 
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Using GitHub for Visual Studio 


FIGURE 13-16: 
The GitHub for 
Visual Studio 
extension in the 
Visual Studio 
Marketplace. 


Visual Studio is different from Visual Studio Code. Visual Studio is an IDE and is a 
full-featured application to support developers in writing code. Both VS Code and 
Atom are editors that have an extensive list of extensions that a developer can add 
to the editor to create the experience they need. Visual Studio has a version for 
Mac and a version for Windows. This section talks only about the version for Win- 
dows because it’s the original and more full-featured version and the one that has 
the GitHub integration. 


After you install Visual Studio, choose Tools Extensions and Updates. A pop-up 
window appears with all the extensions you currently have installed, plus the 
marketplace of additional extensions. If you click Online, the top choice is the 
GitHub Extension for Visual Studio extension, as shown in Figure 13-16. 
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Click the Download button and close Visual Studio. When Visual Studio closes, the 
VSIX Installer starts and ask whether it can modify Visual Studio. When you click yes, 
then modify, the extension begins to install. After it installs, click the Connect link in 
the Team Explorer tab and connect to your GitHub account, as shown in Figure 13-17. 
When you click the Connect link, a pop-up window asks you to sign in to GitHub. If 
you have two-factor authentication set up, you’re also asked for your 2fa code. 
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FIGURE 13-17: 
The Team 
Explorer pane 
with the GitHub 
Connect section. 
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Once connected, you can clone a repo, create a new repo, or sign out from GitHub, 
all from the Connect page on the Team Explorer pane. 


Viewing, creating, and reviewing pull 
requests in Visual Studio 


When you have the project open in Visual Studio that is connected to a GitHub 
repo, you see additional project options on the home page of the Team Explorer 
pane, as shown in Figure 13-18. 


Clicking Pull Requests opens the GitHub pane where all the pull requests on this 
repo are listed, as shown in Figure 13-19. At the top of the list, you can choose to 
see all the open pull requests, closed pull requests, or just all pull requests. You 
can also sort by author. 


If you double-click one of the pull requests, the details open. From here, you can 
see the description, the target and base branch, the current state, the list of 
reviews, and the list of files changed. You can also click the View on GitHub link to 
open a browser window to this pull request on github.com. Click the Checkout 
<branch-name> button to check out the branch associated with this pull request. 
Click the Add your review link to add your own review with inline and overall 
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comments. When you add a review, you can mark it as comment only, approve it, 
or request changes. If you double-click one of the changed files, the diff opens in 
the editor area. If you hover over one of the changed lines, you can add an inline 
comment, very similar to how it is done in VS Code (refer to Figure 13-11). You can 
see all of this in Figure 13-20. 
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Following the GitHub for Visual 
Studio extension 


The GitHub for Visual Studio extension is open source. You can follow the devel- 
opment, report issues, or even contribute to it on GitHub.com. Go to https: // 
github.com/github/visualstudio to find the latest features and documentation 
for how to use the GitHub for Visual Studio extension to improve your develop- 
ment workflow. 


The GitHub team working on the extension often use a tracking issue to track 
what it’s working on. You can find the most recent tracking issue for this project 
by going to the Issues tab on the GitHub repo and filtering the issues by the Next 
Release label. 


Using GitHub for XCode 


Apple has developed an integration for GitHub in XCode. After you install XCode, 
you can sign in with GitHub by choosing XCode Preferences to open the Accounts 
tab. Click the plus sign in the bottom left corner, choose GitHub, and click 
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FIGURE 13-21: 
Signing in to 
GitHub inside of 
XCode. 


Continue, as shown in Figure 13-21. Follow the prompts to sign in to your GitHub 
account. If you have two-factor authentication set up, you are asked for your 
2fa code. 
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Now when you choose Source Control™ Clone, your GitHub repos load below the 
box where you can insert a URL to clone. When you click one, you get information, 
such as the primary language used, the number of forks and starts for this repo, 
and a quick link to the README, as shown in Figure 13-22. 


If you have a file open in XCode, the Source Control menu displays additional 
actions you can perform, such as Commit, Push, Pull, and Fetch and Refresh 
Status. 


This extension isn’t open source, so it’s best to keep up with the latest Apple 
developer news to know what new features may be available. You can read about 
all the source control integrations that Apple releases at https: //developer. 
apple.com/library/archive/documentation/ToolsLanguages/Conceptual / 
Xcode_Overview/UsingSourceCodeControl .html. 
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FIGURE 13-22: 
List of GitHub 
repositories you 
have access to 
clone from inside 
XCode. 
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n) vscode-gitlens Feb 13, 2019, 9:32 PM eamodio 


The We Can Zone (GitHub) 

1) CodingDojo_Presentation Apr 3, 2018, 5:35 PM thewecanzone 
roslyn 
The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs. 
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Using GitHub for IntelliJ 


The IntelliJ IDE from JetBrains has GitHub pull request support for any GitHub 
repo you have open. After you install IntelliJ, you can choose to clone a git project 
from the Start menu, as shown in Figure 13-23. 


A pop-up window asks for a URL. At the bottom of this window, click the Sign in 
to GitHub button. You’ re asked for your GitHub credentials. If you have two-factor 
authentication set up, you are also asked for your 2fa code. After you have suc- 
cessfully logged in, all the GitHub repositories that you have access to appear in 
the drop-down list, as shown in Figure 13-24. 


After you choose a repository and click Clone, a series of pop-up windows prompt 
you to create the IntelliJ project. When the project is open in IntelliJ, you can 
open the GitHub pull request preview by choosing VCS > Git View Pull Requests. 
A new section opens in the IntelliJ window with a list of the open pull requests. 
If you click one, the description and list of changed files opens. If you double- 
click one of the changed files, a diff of that file opens in a new window (see 
Figure 13-25). 
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FIGURE 13-23: 
Clone from 

a git project to 
get started 
integrating 
GitHub into 
Intellij. 


FIGURE 13-24: 
List of GitHub 
repositories you 
have access to 
clone from inside 
Intellij. 
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Mercurial 
Subversion 


& Configure» Get Help v 











@ IntelliJ IDEA 
o- o 





Clone Repository 


Directory: 


https://github.com/srfoster/CodeSpells.git 
https://github.com/srfoster/Conversations.git 
https://github.com/thewecanzone/CodingDojo_Presentation.git 
https://github.com/thewecanzone/GitHubForDummies.git 
https://github.com/thewecanzone/GitHubForDummiesReaders.git f 
https://github.com/thewecanzone/swift-playgrounds.git 

https://github.com/thewecanzone/test-assignment-wecan-student.git 

https://github.com/t hewecanzone/thewecanzone.githu b.io.git 





+ Create New Project 
L Import Project 
te Open 


| Check out from Version Control + 


% Configure Get Help v 








Lastly, you can create a pull request from inside of IntelliJ as well. If you’re on a 
new branch and have already made some changes and committed them to your 
branch, you can choose VSC™Git™ Create Pull Request. In the pop-up window, 
shown in Figure 13-26, specify the base and target branch, title, and description 
of your pull request. 


This GitHub pull request feature is embedded in the IntelliJ IDE, so it’s best to fol- 
low the IntelliJ blog and documentation for up-to-date information on the devel- 
opment of this feature. 
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FIGURE 13-25: 
Viewing a pull 
request from 
inside of IntelliJ. 


FIGURE 13-26: 
Creating a pull 
request from 
inside of IntelliJ. 
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IN THIS CHAPTER 





» Using Chrome Extensions to extend 
GitHub 





» Setting up Probot to personalize 
GitHub 


» Using GitHub Actions to customize 
GitHub 


Chapter 14 
Personalizing GitHub 


hen GitHub created the Atom text editor, it set out to build the most 

hackable text editor ever. The tagline for Atom is “A hackable text edi- 

tor for the 21st Century.” Atom focused on that tagline because it rec- 
ognized that software developers can be very particular about their tools. 
Developers have a lot of opinions about how they work and invest a lot of time 
personalizing their tools to work just the way they want. 


The same is true for GitHub.com itself. GitHub offers an extensive API that lets 
developers write tools to interact with GitHub data in a myriad of ways. Also, since 
GitHub.com runs in a browser, anyone can build browser extensions to customize 


the experience of using GitHub. 


In this chapter, we look at some of the available ways to personalize your use of 
GitHub. 


Using Browser Extensions 


Browser extensions can completely customize the experience of using a browser. 
You can find extensions for every possible scenario you can think of. 
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FIGURE 14-1: 


Configuring the 
Refined GitHub 


252 


extension. 


In this section, we look at a few useful extensions that work with GitHub. Some of 
these extensions are available for multiple browsers, but we focus on Google 
Chrome extensions for brevity. 


For a more comprehensive list of browser extensions that work with GitHub, 
check out my Awesome browser extensions for GitHub repository at https: // 
github. com/stefanbuck/awesome—browser-—extensions-—for-—github. 


Refining GitHub 


The Refined GitHub extension is an open source extension that simplifies the 
GitHub interface and adds some useful features to GitHub.com. The extension is 
available for the Chrome, Firefox, and Opera browsers. 


You can find the source code at https: //github.com/sindresorhus/refined-— 
github. The README has a link to install the extension. Note that when you 
install the extension, you grant it the ability to read and change your data on 
api.github.com, gist.github.com, and github.com. It can also modify data you 
copy and paste. 


After you install the extension, you should see an Octocat icon to the right of the 
address bar. This icon provides some light customization options. One option lets 
you define some custom CSS specific to GitHub.com. In Figure 14-1, you can see 
I added some custom CSS to make the repository name larger and dark red. Note 
that after you change the CSS, you have to refresh the page to see your changes in 
effect. 








Ihub.com/thewecanzone/GitHubForDummiesReader x # 
e A egies Custom CSS (useful to undo unwanted styles) 
.repohead-details-container strong a { 
font-size: 26px; 
color: #630; 
thewecanzone / GitHubForDummiesReaders v Qwateh~ 0 > 
<> Code Issues 2 Pull requests 4 Projects 0 Wiki More ~ Settings Features to disable, by filename (not advised) 





For example 
nark-unread hide-own-stars 
This is a repository where all GitHub For Dummies readers can add a link to their GitHub profile! 


github education markdown novice Manage topics Personal token, found here (for high rate API calls and private repos) 





®9 commits P 5 branches 0 releases f 1 environment 28 1 contribute 
Show the features enabled on each page in the console 


Branch: master + Create new file f 
Want more features? Check out our related GitHub extensions 


EE southais update cooeowners Latest ( 
if you're a GitHub Enterprise user, visit your Enterprise site, right-click on 
github Update CODEOWNERS Refined GitHub’s icon in the toolbar and select Enable Refined GitHub on 


this domain. 
LICENSE Initial commit 











Changing the CSS is just a parlor trick compared to the many other enhancements 
Refined GitHub brings with it. 
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WARNING 


Browser extensions work by manipulating the generated HTML of a website. It 
often looks for known landmarks in the pages (such as an HTML element with a 
known ID) and then adds its own UI elements, removes elements, or changes ele- 
ments. However, it does this all outside of the code running on the server that 
actually generates the HTML. What this means is that if a website such as GitHub. 
com changes their HTML mark-up, an extension feature could stop working tem- 
porarily until the authors update their extension to adapt to the new change. So if 
any of these features stop working, try again later after the extension is updated. 


The following is a small sampling of enhancements that are on as a default when 
you have this extension installed: 


>> Mark issues and pull requests as unread. This enhancement adds a Mark 
as unread button to the Notifications section of an issue or pull request. Click 
it to mark the issue or pull request unread, which puts it back in your notifica- 
tions list. 


>» Stop the page jumps from recently pushed branches. Normally, when you 
push a new branch, the home page of a repository displays a list of recently 
pushed branches in a yellow bar above the list of code files. The sudden 
appearance of this list can cause the rest of the page to jump down to make 
room for the bar. Refined GitHub displays the list of recently pushed branches 
in the top right overlaying the location where the Fork button may be. By 
displaying the branches in an overlay, Refined GitHub ensures that the page 
doesn't jump down. 


>> Adds option to wait for successful checks. If you have continuous integra- 
tion (Cl) set up for a repository, it can take a while after someone pushes a pull 
request before all the checks are completed. The Cl might be running static 
analysis or a linter, unit tests, integration tests, and so on. It can be annoying 
to wait for all of those processes to complete after you've reviewed some code 
and are ready to merge the pull request. Refined GitHub adds a check box 
that lets you indicate that it should go ahead and merge the pull request after 
the checks are complete and successful. 


>> Reaction avatars show who reacted to a comment. Typically a reaction 
comment shows only the reaction and the count for that reaction. With 
Refined GitHub, you can see who all gave a specific reaction. 


Refined GitHub contains many more enhancements big and small. The list here is 
just the tip of the iceberg. In Figure 14-1, notice that there is also a place to disable 
features that are a part of the extension, as well as a place to put your GitHub 
personal access token so that the extension can work on private repos as well. 
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FIGURE 14-2: 
Taking a short 
video with GitHub 
Selfie. 


Taking a GitHub selfie 


As an open source project maintainer, I am ecstatic when someone comes along 
and submits a pull request for a project. I’m happy when someone opens an issue 
that identifies a problem I didn’t know about. I feel gratitude for the folks that 
take time out of their day to help out my project. 


And sure, I could use words to communicate my gratitude, but they always seem 
to fall short of my true feelings. If the old saying that a picture is worth a thousand 
words is true, how many words is an animated gif worth? 


GitHub Selfie is an open source browser extension (https://github.com/ 
thieman/github-sel fies) that adds a Selfie button to the comment field that lets 
you take a selfie using your computer’s camera. You can choose to take a still pic- 
ture, but where’s the fun in that? It also provides an option to take an animated gif. 


Figure 14-2 shows one of the authors using the GitHub Selfie to take a ridiculous 
self-portrait. 





2! Write Preview MBi «ov FEE ORMS 


Selfie! Close issue 











Duration: | 1s + LEE | Video Photo 





Adding a selfie to express your gratitude is a small detail, but adds a nice warm 
personal touch to working together with people from all over the world. 
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GitHub Apps and Probot 


Chapter 13 covers a few integrations that connect GitHub to other applications, 
such as Slack and Trello. What those integrations have in common is they were 
implemented as GitHub apps. 


Apps on GitHub let you extend GitHub in powerful ways. GitHub apps are web 
applications that can respond to events on GitHub. These event subscriptions are 
called web hooks. When an event occurs on GitHub that the app is interested in, 
GitHub makes an HTTP request to the app with information about the event. The 
app can then respond to that event in some manner, often resulting in a call back 
to GitHub via the GitHub API. 


In this section, we walk through building a simple GitHub App that brings a bit of 
levity to your issue discussions. There’s an old meme in the form of an animated 
gif with a little girl who asks the question, “Why don’t we have both?” The typical 
application of this meme is in response to a question that presents a false dichot- 
omy. In other words, when someone presents a question with two choices, some- 
one might respond with this image. 


In this section, you create a GitHub application that will automatically do this as a 
fun exercise. 


Introducing Probot 


GitHub apps are web applications that need to listen to HTTP requests. You have a 
lot of important details to get just right when building an HTTP request, such as 
what is the format of the data posted to the app? All these details can be confusing 
and time consuming to get correct when building a GitHub app from scratch. 
Knowing where to start is difficult. 


GitHub’s Probot framework comes in handy when getting started with a GitHub 
app. Probot handles much of the boilerplate and nitpicky details of building a 
GitHub app. It is a framework for building GitHub apps using Node.js. It provides 
many convenience methods for listening to GitHub events and for calling into the 
GitHub API. 


Probot makes it easy to build a GitHub app, but it doesn’t solve the problem of 
where to host the app. 
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Hosting the app 


A GitHub app can take many forms. It could be a Node.js app running in Heroku, 
an ASP.NET Core app running in Azure, a Django app running in Google Cloud — 
it doesn’t matter. It just needs to be persistent and available via the public Inter- 
net so that GitHub can reach it with event payloads. 


Setting all that up can be time consuming, so for our purposes, we use Glitch to 
implement a quick and dirty GitHub app. 


Introducing Glitch 


Glitch (https: //glitch.com) is a hosting platform for web applications that 
removes a lot of the friction with getting a web app up and running. Any app you 
create in Glitch is live on the web from the beginning. You don’t have to think 
about how you plan to deploy the code because any change you make is auto saved 
and automatically deployed. 


Glitch focuses on the community aspect of building apps. Every file can be edited 
by multiple people in real-time, in the same way you might edit a document in 
Google Docs. And every project can be remixed by clicking a button. This encour- 
ages a lot of sharing of code and learning from each other, which comes in handy 
when we build our own GitHub app. 


Before you continue, make sure to create an account on Glitch if you don’t have 
one already. 


Creating a Probot Glitch app 


After you have a rough understanding of Probot and have a Glitch account set up, 
you can build a Probot app on Glitch. Glitch lets you remix existing apps, and the 
good news is Glitch already has a Probot app that you can remix. This means you 
can create your Probot app with one click and a few customizations. 


To create your app, type the following URL into your browser: https: //glitch. 
com/edit/#! /remix/probot-hello-world. 


This command creates a brand new app in Glitch based on the probot-hello- 
world example with a randomly generated URL, as shown in Figure 14-3. As you 
can see, my app is called candy-chaf feur. 
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FIGURE 14-3: 
The README 
page of a Glitch 
Probot app. 


WARNING 





& <> candy-chauffeur éc Show MD README. md 


@ S < © Markdown 


TATA Welcome to Probot on Glitch 


T assets This is the Glitch equivalent of running create-probot-app to generate a new 


meny probot app locally. Updates to your code will instantly deploy and update live. 
„gitignore 


„travis. yml 


LICENSE > 
Getting Started 


app. json 
index. js 
package. json 


To get your own Glitch-hosted Probot up-and-running, follow these steps. If you 
need more detail, the Probot Docs are a great place to go to learn more. 


1. Configure a new app on Github. 





« Hit the "Show" button on the top left of this page to find the URL. It will 
look something like https: //random-word.glitch.me/probot , except 
the domain will be specific to your app. 

» For the Webhook URL, use this URL (again, updating the domain to 
match yours): https://random-word.glitch.me/ . Notice that we left off 
the /probot. 

« For the Webhook Secret, just use "development". until Step 4. 

» Save your changes. 

» On the Permissions & webhooks tab, add read and write permissions 








The left pane shows the list of files in your application. The README .md file 
contains step-by-step instructions to set up the hel 1lo-world Probot app. Follow 
these instructions carefully to set up the sample GitHub app. 


One of the instructions mentions running the following command: 
cat my—app-name.2018-06-20.private-key.pem | pbcopy 


The purpose of the previous command is to copy the contents of your private key 
file into the clipboard so that you can paste it into the Glitch file. However, this 
command works only on a Mac. On Windows, you would run the following com- 
mand (changing the file name to match yours): 


type my-app-name . 2018-06-20 .private-key.pem | clip 
When you are done, install the app on a repository that you own and then create a 


new issue. A few seconds later, you should see a comment created by your bot with 
the words “Hello World!”. 


Customizing the app 


After you create a Probot app in Glitch and install it on GitHub, you can customize 
how the app responds to issue comments. When you followed the steps in the 
README, you subscribed to issue events. These events do not include when new 
comments are created. We need to also subscribe to issue comments. 
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You can see a list of your apps at https: //github.com/settings/apps. Click the 
Edit button to navigate to your app. Then in the left navigation, click Permissions & 
events and scroll down to the Subscribe to events section. Check the Issue com- 
ment check box, as shown in Figure 14-4. 





Subscribe to events 


Based on the permissions you've selected, what events would you like to subscribe to? 


Security advisory @ Issue comment @ 

Security advisory published, updated, or withdrawn. Issue comment created, edited, or deleted. 
Issues @ Label © 

Issue opened, edited, deleted, transferred, pinned, Label created, edited or deleted. 


unpinned, closed, reopened, assigned, unassigned, 


labeled, unlabeled, milestoned, or demilestoned. = 
Milestone © 


Milestone created, closed, opened, edited, or deleted. 


Public @ Pull request @ 

Repository changes from private to public. Pull request opened, closed, reopened, edited, assigned, 
unassigned, review requested, review request removed, 
labeled, unlabeled, or synchronized. 


Pull request review @ © Pull request review comment @ 
FIGURE 14-4: Pull request review submitted, edited, or dismissed. Pull request diff comment created, edited, or deleted. 
Updating 
the event Repository © Watch © 
Repository created, deleted, archived, unarchived, User stars a repository. 


subscriptions for 
the GitHub app. 


publicized, or privatized. 











Click the Save changes button at the bottom to complete these changes. 


Now you need to change your Glitch app to listen to new issue comments and 
respond appropriately. Edit the index. js file and replace the contents of the file 
with the following code: 


module.exports = (app) => { 


// Listens to new issue comments 
app.on('issue_comment.created', async context => { 


// Retrieves the comment text 
const message = context.payload.comment. body 
if (message.indexOf(' or ') > -1) { 
const params = context.issue({ 
body: '! [The why not both girl] (https: //media3.giphy. 
com/media/3085x103317R1mLR41/giphy.gif)' 
1) 
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FIGURE 14-5: 
The why not both 
app in action. 


// Creates a comment with a markdown image 
return context.github. issues.createComment (params) 
} 
}) 
} 


This code listens to new issue comments, looks for the word or surrounded by 
spaces, and if it finds it, creates a new comment with a markdown image. 


This approach is not very smart. You can find a slightly better approach at 
https: //git.io/fhHST. It would be even better if we could employ some artificial 
intelligence (AI) in the form of natural language processing (NLP). But that’s 
beyond my skillset and out of the scope for this book. 


Installing the app 


After you create the app and get it working, others can install the app and use it. 
For example, we already built a version of the app that we are currently describing 
in this section. You can install it by going to https://github.com/apps/ 
why-not-—both and clicking the big green Install button in the top right. 


Install it on a repository and then go create a comment on an issue in the reposi- 


tory that asks a question with the word or in it. An example interaction is shown 
in Figure 14-5. 


a Haacked commented 3 minutes ago Member 


I'm not sure what to do here. Do | demonstrate the Trello integration or a different integration? 


oe why-not-both bot commented 3 minutes ago 
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Taking Action with GitHub Actions 
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TIP 


In the previous section, we walk through personalizing GitHub by creating a 
GitHub app. This required that we host our app outside of GitHub. It turns out 
GitHub has a feature that removes the need to host our app outside of GitHub, 
which can reduce the number of moving parts when extending GitHub. This fea- 
ture is called GitHub Actions. 


GitHub Actions is one of the newer, most exciting features of GitHub. At the time 
of writing, it’s still a beta feature. GitHub Actions makes it possible to create cus- 
tom workflows on GitHub. It lets you implement custom logic to respond to events 
on GitHub. In the previous section, we wrote a GitHub app to do that. With GitHub 
Actions, we don’t need to build a custom app. We can build workflows using exist- 
ing actions that others have written, or we can write our own actions that run in 
a Docker container. 


Hopefully, by the time you read this, GitHub Actions are generally available. But in 
the case they’re still in beta, email support@github.com and ask to be in the 
GitHub Actions beta program. 


To demonstrate GitHub Actions, consider the following scenario. When you merge 
a pull request in your own repository, the branch for the pull request sticks around. 
GitHub presents a button to delete the branch, but a lot of people forget to do so 
and leave these branches sticking around. 


Not deleting the branch isn’t necessarily a bad thing, unless you’re the type of 
person that likes things to be tidy and cannot stand having a branch that’s no 
longer needed lingering around. If you are that type of person, you’re in luck. 
Jesse Frazelle is also that type of person, and she wrote a GitHub Action you can 
use in your own workflows. Her blog post, “The Life of a GitHub Action” at 
https://blog. jessfraz.com/post/the-1ife-of-a-github-action, is a good 
read to understand more details about the life cycle of a GitHub action. 





Creating a GitHub action workflow 


If you’ve been accepted in the GitHub Actions beta program or it has become more 
widely available, you should see an extra tab at the top labeled Actions when you 
view a repository. 


The following steps walk through the process for creating a GitHub action work- 
flow for a repository. 
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1. Click the Actions tab to see your existing workflows. 


If you don't have any workflows yet, you see a big green button to Create a new 
workflow, as shown in Figure 14-6. 


GitHub Actions tab 


[| Haacked / haacked.com @unwatchy 11 wkstar 117  YFork 


Code Issues 2 Pull requests 0 Insights Settings 


Set up actions and workflows 








©) 
O-O 


OO 


GitHub Actions 


Create your first workflow 


GitHub Actions compose end-to-end workflows. Workflows can be triggered by 
GitHub Platform events like push, new issue, or new release. 


FIGURE 14-6: 


The landing 

page for 
GitHub Actions | 

workflows. Create a new workflow button 














2. Click the Create a new workflow button to bring up the workflow 
designer view. 


This visual designer lets you create workflows and connect them to actions. 
Workflows are stored in a file named main. workflow in the . github directory 
of your repository. There's also an editor view if you prefer to build your 
workflows with text. 


3. switch to the text editor and paste in the following text: 


workflow "on pull request merge, delete the branch" { 
on = "pull_request" 
resolves = ["branch cleanup" ] 


} 


action "branch cleanup" { 
uses = "jessfraz/branch-cleanup—action@master" 
secrets = ["GITHUB_TOKEN"] 
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FIGURE 14-7: 


Committing a 
simple workflow. 
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TIP 


If you switch back to the visual designer, it should look something like 
Figure 14-7. 


4. Click the Start commit button to commit this new main. work flow file to 
your repository. 





[3 Haacked / haacked.com @unwatchy 1 wkstar 17 YFork 148 


<> Code Issues 2 Pull requests 0 Actions Insights Settings 


haacked.com /.github/ main.workflow or cancel T Fullscreen 


(Visual editor <> Edit new file © Preview P 
Commit new file 


Create a new workflow 


on pull request merge, delete the branch 
on: pull_ request on pull request merge, delete the 


Q branch 


on pull_request 





© © Commit directly to the master branch. 


1) Create a new branch for this commit and start a 
pull request. Learn more about pull requests. 


= Commit new file 
branch cleanup Q 


Branch Cleanup 


uses jessfraz/branch-cleanup-... 
secrets (€)GITHUB_TOKEN 


Edit 











Testing a GitHub Action 


After you commit this file to your repository, the workflow is active. You can test 
it by creating a new pull request and then merging it. A few seconds or minutes 
later, you should see that the pull request branch was deleted. An update on the 
pull request says something like 


github-actions bot deleted the branch-name branch 1 minute ago 


You can create pretty useful and complex workflows using existing actions. You 
can install actions from the GitHub Marketplace or reference them by pointing to 
a repository that contains an action. You can also write custom actions. How to do 
that is beyond the scope of this book, but you can look at the action that Jesse 
wrote at https: //github.com/ jessfraz/branch-cleanup-action to get an idea 
of what it takes. 


With GitHub Actions, you can personalize GitHub to your tastes in nearly unlim- 
ited ways. 


PART 5 Make GitHub Work For You 


Tħe-GitHub 
Ecosystem 


IN THIS PART... 


Review the GitHub Marketplace for apps to enhance 
your project. 


Install apps for continuous integration, code quality, 
localization, and more. 


List your app on the GitHub Marketplace. 


Explore the community on GitHub.com through people 
and repositories. 


Find events where you can discover community beyond 
GitHub.com. 


Discover strategies for speaking at your first event. 


IN THIS CHAPTER 


» Introducing the GitHub Marketplace 





» Finding apps in the Marketplace 


» Installing apps from the Marketplace 


Chapter 15 


Exploring the GitHub 
Marketplace 


n the three chapters of Part 5, we look at multiple different ways of extending 
GitHub and customizing the GitHub experience. Many tools extend or integrate 


with GitHub. A good way to find tools to use with GitHub is the GitHub 
Marketplace. 


Introducing the GitHub Marketplace 


The GitHub Marketplace (https://github.com/marketplace) is a directory of 
tools and apps grouped in the following categories: 


>> Chat 
>> Code quality 


>> Code review 
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>> Continuous integration 
>» Dependency management 
>> Deployment 

>> Learning 

>> Localization 

>» Mobile 

>> Monitoring 

>> Project management 
>> Publishing 

>» Recently added 

>> Security 

>> Support 

>> Testing 


>» Utilities 


The Marketplace is a great way to find an app for every situation on GitHub. 
Purchasing or installing apps through the Marketplace has two key benefits: ease 
of billing and installation and the vetting process. 


Billing made easy 


For apps in the GitHub Marketplace that require payment, installing the app 
through the Marketplace is a streamlined flow because you can use your GitHub 
payment info. That way, you’re not dealing with five different payment providers 
when purchasing five different apps to use with GitHub. 


If you have a free GitHub account, you may not have setup your payment informa- 
tion in GitHub. To set up a payment method, click your avatar in the top right 
corner of GitHub.com and click Settings. From this page, click Billing from the list 
on the left side. Here you can click the Add payment method, as shown in 
Figure 15-1. 
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FIGURE 15-1: 
Your Settings 
page on GitHub. 
com where you 
can add payment 
information. 


WARNING 





Personal settings Billing overview 





Profile 
Plan GitHub Pro - Pro tools for developers with advanced requirements 
Account 
Emails Git LFS Data $0 per month for O data packs - Learn more about Git LFS Purchase more 
Billing cycle - 17 days left, billed monthly 
Notifications iis 
jai llı Bandwidth - Using 0.0 of 1 GB/month ®© 
Billing 


e iea 
SSH and GPG keys S Storage - Using 0.48 of 1 GB 


Security 


Morkotpiace You have not purchased any apps from the Marketplace. 
Sessions pps 
Blocked users N 
Payment 5 No payment method on file. E Add payment method 
Repositories 
Organizations Coupon You have an active coupon for $25.00 off forever. 
Saved replies 
Extra info@ You have not added any additional information for your receipts. @ Add information 
Applications 








The Marketplace vetting process 


One of the benefits of installing an application from the Marketplace is that these 
apps must meet certain requirements before GitHub will list them in the Market- 
place. The requirements help ensure a higher standard of quality and security with 
the apps; helping ensure that these apps are useful (no Fart apps) and are secure. 


At the moment, a GitHub Action doesn’t require any review to be listed in the 
GitHub Marketplace, which means installing an action from someone you don’t 
know may be a bit riskier. 


An app must meet four main categories of requirements before being listed in the 
Marketplace (https: //developer .github.com/marketplace/getting-started/ 
requirements-for-1isting-an-app-on-github-marketplace): 





>> User experience: This brief set of nine requirements includes things like the 
app must have a certain number of users and installs already. It also includes 
some requirements around the behavior of the app, such as the app must 
include links to documentation, it can’t actively persuade users away from 
GitHub, and it must provide value to customers. 


>» Brand and listing: This set of guidelines and recommendations center 
around the branding of your app and your app's listing. Every app must 
include its own logo. If the app makes use of GitHub’s logo, it must follow 
GitHub’s Logos and Usages guidelines. The brand and listing section on the 
Requirements page has links to further logo and description guidelines. As 
you can see, GitHub takes listing apps in the Marketplace seriously. 
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>> Security: GitHub will conduct a security review of apps before listing them in 
the marketplace. A separate document with security best practices and more 
details on the security review is at https: //developer .github.com/ 
marketplace/getting-started/security-—review-process. 


>? Billing flows: Every app in the Marketplace must integrate billing flows using 
the GitHub Marketplace webhook event. This requirement ensures that 
people can purchase a subscription to your app and cancel that subscription 
with the payment info they already have on file with GitHub. It also ensures 
that any changes made through GitHub are reflected immediately on the 
app’s own website. 


Listing Your App on the Marketplace 


Getting your own app listed in the Marketplace may increase the potential audi- 
ence for your application. However, listing your app requires that it meets GitHub’s 
requirements and receives approval. Chapter 14 guides you through creating your 
own app. 


To start the process of listing an app, click the Submit your tool for review link at 
the bottom of the Marketplace landing page or navigate to https: //github.com/ 
marketplace/new in your browser. 


This page lists your applications that you can turn into Marketplace listings, as 
shown in Figure 15-2. Notice the Why Not Both app we create in Chapter 14 is 
listed here. 





List your tool on GitHub Marketplace 


Create a draft GitHub Marketplace listing from one of your tools 


orbs Create draft listing 
eo Create draft listing 
SA ered Create draft listing 
FIGURE 15-2: 
Your applications a agi Create draft listing 


that you can turn 
into Marketplace 
listings. 


© Your tool must meet the requirements for GitHub Marketplace in order to be approved. 
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FIGURE 15-3: 
Filling out a form 
to list an app. 


TIP 


Click Create draft listing next to the app you want to list on the Marketplace to 
start the process. This takes you to a page where you can enter a name for the list- 
ing and choose one of the marketplace categories for your app listed earlier in the 
chapter, as shown in Figure 15-3. 





Create a new GitHub Marketplace draft listing 


Listing name 
Why Not Both 


Limit 255 characters. 243 remaining. 
A human-friendly name for your listing. 


Primary category 


Open Source management + 


Save and add more details 








If you save the draft of your listing but happen to close your browser, you can get 
back to your listing by going to https: //github.com/marketplace/manage in 
your browser. 


After you fill in these details, click Save and add more details to save a draft of 
your listing and move on to the next set of steps, as shown in Figure 15-4. 


These steps include 


1. Add your contact info. 


This info is a set of three email addresses: Technical lead, marketing lead, and 
finance lead. 


2. Fill out your listing description. 


This area is where you fill out more details, such as a product description, logo, 
and screenshots. The information here will be displayed on the Marketplace 
page for your application. 


3. set up plans and pricing. 


This is where you can set up one or more pricing plans, including the option to 
create a free plan, a monthly plan, or a monthly per user plan. You can also 
specify whether a plan includes a 14-day free trial. 
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Marketplace Edit Why Not Both Overview © Preview listing 
E Publish your app to Marketplace 
Why Not Both To publish your app to GitHub Marketplace, complete the following items. Once completed, you can 
submit your listing to us for review. 
Overview Draft 
6 Add your contact info 
Listing settings 
Contact info {v 
2 Fill out your listing description 
Listing description . 
A Naming and links 
Plans and pricing bd Product name, categories and supported languages. 
Webhook . 
Logo and feature card 
These assets will be used for marketing your product. 
Listing details 
Detailed description of your product for use on your GitHub Marketplace page. 
Product screenshots 
High resolution screenshots to be shown on your GitHub Marketplace page. 
3 Setup plans and pricing 
FIGURE 15-4: 
Steps to fill out a 
Marketplace 4 Setup webhook 
submission. 





4. set up webhook. 


This step allows you to specify a URL where Marketplace events will be sent via 
an HTTP POST request. The webhook will send you information about events, 
such as purchases, cancellations, and changes like upgrades and downgrades. 


5. Accept the Marketplace Developer Agreement. 


In order to list your app in the marketplace, you have to accept the 
Marketplace Developer Agreement. 


6. Click the Submit for review button. 


GitHub employees will review your submission to make sure it meets the 
requirements to be listed in the Marketplace. 


Considering Common Apps to Install 


In the section “Introducing the GitHub Marketplace” at the beginning of this 
chapter, we list the categories of apps that are available on the Marketplace. In 
this section, we describe some of the most common and useful apps that you may 
want to consider installing. 
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FIGURE 15-5: 
AppVeyor Cl app 
example on the 
GitHub for Visual 
Studio repository. 


Continuous integration 


Continuous integration (CI) apps automatically build and test your code every 
time you push it to GitHub. If you have a CI app, such as AppVeyor, installed on 
your repository, you will see the status of the check at the bottom of each pull 
request, as shown in Figure 15-5. 





© 1 approving review by reviewers with write access. Show all reviewers 
(~) 3 successful checks Hide all checks 

SA. (9) continuous-integration/appveyor/branch — AppVeyor build succeeded Details 

v (9] continuous-integration/appveyor/pr — AppVeyor build succeeded LOM Details 

v . github.VisualStudio Successful in 6m — Build #20190213.7 succeeded Details 











If you’re the owner of the repository, you can also specify whether checks have to 
pass before the branch can be merged into the master branch. Just head into the 
Settings tab. If you have any rules on the master branch already, click edit; other- 
wise, click Add Rule. From there, you can scroll down and select Require status 
checks to pass before merging. 


Code quality 


Code quality apps automatically review your code with style, quality, security, and 
test-coverages checks. These apps can be really useful for ensuring your code is 
kept to a high standard. With well-styled and quality code, you’re less likely to 
introduce or miss bugs. For example, if you require that all curly braces are on new 
lines and indented with one tab per nested brace, you’re likely to be able to spot 
when something is incorrect. For example, Rubocop checks the style of your Ruby 
code while it’s building and provides you with style feedback, such as casing for 
method names. 


Another useful type of code quality apps is the code coverage apps, such as Code- 
cov. Shown in Figure 15-6, Codecov and apps like it comment on pull requests 
with how much of the code is covered by test scenarios, helping to ensure your 
code remains well tested. 
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FIGURE 15-6: 


Codecov app 
example on the 
GitHub package 


272 


for Atom 
repository. 





codecov bot on Jan 10 <> + edited + 
Codecov Report 


nto master will decrease coverage by 9.17% 
age is 30% 








Files 185 185 
Lines 10719 10739 128 





Impacted Files Coverage A 
lib/controllers/root-controller js 88.51% <o> (-3%) 
lib/models/repository.is 96.21% <1@0%> (40.11%) 
lib/models/repository-states/present,js 95.06% «100% (-0.37%) 
lib/models/conflicts/side.js 92.18% <OK> (-4.69%) 
lib/atom/decoration.js 84.33% <O%> (-2.41%) 


lib/controllers/editor-conflict-controller,js 94.94% <@X> (1.62%) 


SBacococeas 


lib/git-shell-out-strategy.js 87.7% <0%> (48.17%) 


Continue to review full report at Codecov. 


Legend - Click here to learn more 
A = absolute <relative> (impact), @ = not affected, ? = missing data 
Powered by Codecov, Last update 4786390...118fbff. Read the comment docs. 








Localization 


Localization apps can make publishing your app in many languages easier. For 
example, the Crowdin app will link your repository to a Crowdin account where 
people from around the world can help you translate your documentation and any 
written words in your software (for example, on buttons or in menus). With more 
than 20,000 people contributing to translations, the Crowdin app will automati- 
cally open a pull request on your repository with new translations when it’s 
reached a threshold of accuracy, still giving you a chance to review and merge. For 
open source projects, Crowdin is free! 


Monitoring 


Monitoring apps help measure performance, track errors, and track dependencies 
in your code. For example, Greenkeeper is a real-time notification app that gives 
you updates and changes for JavaScript dependencies. Figure 15-7 shows Green- 
keeper in action, opening a pull request to update eslint to the latest version. 
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FIGURE 15-7: 
Greenkeeper app 
example on the 
GitHub package 
for Atom 
repository. 





Update eslint to the latest version ¥ 


Suleyes-um greenkeeper wants to merge 2 commits into master from greenkeeper/eslint-5.14.@ * Jump to bottom 


C& Conversation 1 © Commits 2 E Checks 12 Files changed 2 


H greenkeeper bot 3 days ago Contributor 


The devDependency eslint was updated from 5.12.0 to 5.14.0. 


This version is not covered by your current version range. 


If you don't accept this pull request, your project will work just like it did before. However, you might be 
missing out on a bunch of new features, fixes and/or performance improvements from the dependency 
update. 


> Release Notes for v5.14.0 
>» Commits 
> FAQ and help 


Your Greenkeeper bot ka 











Dependency management 


Modern app development today is heavily dependent on public package managers 
for pulling in and managing dependencies. A typical app may have dozens, if not 
hundreds, of dependencies. Tracking which of these dependencies are up-to-date 
can be difficult. Github apps like Dependabot check to make sure your dependen- 
cies are up-to-date and submit pull requests to update the ones that are not. 


Sometimes you don’t want all your dependencies on a public package registry. For 
example, if you work in an enterprise, you may have internal packages that should 
remain private. A private package registry tool, such as MyGet, is useful in this 
case. MyGet works with NuGet packages and lets you set up a policy where pushes 
to a particular branch will initiate a build and the branch will be deployed to a cus- 
tom NuGet feed hosted on MyGet. 


Testing 


Testing software is an important part of the software development lifecycle. Good 
testers develop test plans to ensure that testers do a good job of testing each 
release. Managing test plans and keeping track of the status of test runs is an 
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important part of quality assurance. The TestQuality app integrates with GitHub 
to helping developers and testers create, run, coordinate, and monitor software 
testing tasks. 


Learning 


A great way to learn GitHub is to install the GitHub Learning Lab from the 

Marketplace. Installing Learning Lab install a bot that walks you through 

interactive lessons on how to use GitHub through a set of tasks that you complete. 
TIP The lab is free and lets you take as many courses as you like at your own pace. 
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IN THIS CHAPTER 


» Making the most of your profile 





» Understanding your contribution 
graph 


» Following people and starring 
repositories 


Chapter 16 
GitHub and You 


itHub is often described as a social network for developers. Throughout 

this book, we show you that GitHub is much more than a social network. 

It’s an essential set of tools for working on code together. Even so, the 
social network aspect is still an important part of GitHub. It may well be a key 
reason for its success. When GitHub was created, there were existing source con- 
trol hosts. Pretty much all these hosts were focused around projects. GitHub 
turned this project-focus approach on its head and made people the focus. You can 
see it in the URL structure where every repository has the name of the user or 
organization before the repository name. 


In this chapter, we dig into the social network aspect of GitHub. We look at how 
you represent yourself in this network and how you can get involved in the online 
community. 


Understanding Your GitHub Profile 


Every user on GitHub has a profile page. Figure 16-1 shows the profile for one of 
the authors of this book at https: //github.com/haacked. 
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FIGURE 16-1: 


The profile page 


276 


for Haacked. 


WARNING 


Status message 


Profile pic Pinned repositories 


Stars 42 





Overview Repositories 70 Projects 0 Followers 2.6k Following 15 





Working from home 


Phil Haack 


Haacked 


* 2 


Not much to say that | haven't 


Pinned repositories 


= SeeGit 
SeeGit - The Git Repository Visualizer 
¥ 102 


Oct *442 


= RouteMagic 


Utility Library to get the most out of ASP.NET Routing. 


@c# *170 Yas 


= Encourage 


Customize your pinned repositories 


= github/Scientist.net 


A ..NET library for carefully refactoring critical paths. It's a 
port of GitHub's Ruby Scientist library 


@ce wk Yo 


= Rothko 


An abstracted library for interacting with the file system, 
registry, etc. 


@ce #73 Yis 


= encourage-atom 


said at http://haacked.com/about/ 


A bit of encouragment added to Visual Studio An Atom extension that adds little encouragements while 


you work 
42 GitHub 

© Bellevue, WA 

®© http://naacked.com/ 


@c# xeo Y¥36 ® JavaScript w22 Y¥10 


2,386 contributions in the last year Contribution settings ~ 


Edit 





Organizations 


omg 


Learn how we count contributions. Less MMMM More 

















Personal info and bio Contributions graph 


Your profile page represents you on GitHub. When you open an issue or submit a 
pull request to a new repository, the maintainers are likely to take a look at your 
profile to get a sense of you. 


Not only that, your GitHub profile can serve as a portfolio of your development 
work. It provides some insight into your interests, experience, and ability as a 
software developer. Many companies who are hiring will take a look at your 
GitHub profile. 


Many companies give heavy weight to applicants that have a GitHub profile. How- 
ever, this biases against people who don’t have the benefit of working at a com- 
pany that uses GitHub. It also biases against those who don’t have free time to 
work on open source. GitHub, Inc. itself doesn’t require a strong GitHub profile to 
apply for a job. More and more companies are taking an approach where they’ll 
look at your GitHub profile if you have one, but won’t hold it against you if you 
don’t. 


PART 6 The GitHub Ecosystem 


TIP 


FIGURE 16-2: 
Changing your 
status message. 


Profile picture 


The first thing people visiting your profile will notice is your profile picture. This 
pic is associated with all your activity on GitHub. When you create an issue or a 
pull request or leave a comment, your profile pic is right there next to it. 


Your photo is an important part of your GitHub identity so make it reflect your 
personality, whether it’s a picture of you smiling warmly, a photo of a cartoon 
character, or a landscape photo. 


Status message 


Under your profile pic is a status message you can use to communicate something 
about yourself to the entire community. For some, it is an outlet to say something 
funny or meaningful. But for others, it’s used for practical purposes. For example, 
if you’re a maintainer of a popular project, you may want to let the world that 
you’re busy if you plan to be away from GitHub for a while. That sets the expecta- 
tion that you may be slow to respond to new issues. Click your status message to 
bring up the option to change it. Figure 16-2 shows the status message dialog box 
with a busy message specified. 


Edit status x 


$4 | I'm busier than a gopher on a golf course 


Busy 
When others mention you, assign you, or request your review, GitHub 
will let them know that you have limited availability. 


My status is visible to Everyone ~ 








Personal info and Bio 


GitHub displays your bio and information that you choose to show the world under 
the status message. Click the Edit button to change your bio, company name, 
location, and URL. This area is a good opportunity to tell the world a bit more 
about yourself and link to your personal blog or website. 
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REMEMBER 


FIGURE 16-3: 
Staff badge ona 
GitHub profile. 


All this information is completely optional. By entering it, you give GitHub per- 
mission to display this information wherever your user profile appears. You can 
delete the information at any time by editing your profile. 


In this section, you also sometimes find badges that GitHub will add to users’ 
profile. For example, in Figure 15-1, you can see that Haacked has the Pro badge. 
Haacked is definitely a pro GitHub user, but that’s not what that badge means. 
A Pro badge on a GitHub profile just means that that user pays for the individual 
Pro subscription. (You can see different pricing models at https: //github.com/ 
pricing.) Another badge you may often see is the Staff badge. This badge is 
reserved for full-time employees at GitHub (also called Hubbers). Figure 16-3 
shows meaghanlewis’s profile with the staff badge. Meaghan happens to be the 
technical reviewer for this book and is an engineering manager at GitHub! 








Meaghan Lewis 
meaghanlewis 


Follow 


Block or report user 


Quality Engineer 








22 GitHub 





Pinned repositories 


By default, GitHub shows a selection of your most popular repositories on your 
profile page, but those repositories may not represent what’s important to you. 
Click Customize your pinned repositories to select up to six repositories to pin to 
your profile page. 


Pinned repositories can be useful from three perspectives: 
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REMEMBER 


TIP 


>> You: Pinned repositories are useful to you because they're a quick link to the 
repositories you care about most. Pinning repositories can make it quick and 
easy for you to get there, instead of having to create bookmarks for 
each of them. 


>> Other GitHub users: When other people visit your profile on GitHub, the first 
introduction to the kind of work you do is the set of your pinned repositories. 
This will give folks a sense of what you're interested in. It also highlights the 
areas where you have experience. Listing areas of experience can be impor- 
tant if you're just starting to contribute to a new open source project because 
maintainers will often visit your profile page to get a sense of who you are. 


>> Companies: Hiring managers and recruiters may look at your profile when 
you apply to a job to get a sense of your experience. Pinning some projects 
that you have most contributed to or are most proud of to the top of your 
profile can help them to get an accurate picture of you. 


You can also always change up your pinned repositories based on what you’re 
doing. For example, if you’re applying for a new position, you may want to refresh 
what is pinned to be more specific to the role you’re applying to. And if you’re 
trying to learn something new, you may want to pin repositories that you’re 
currently engaged with. Think of your entire profile page as a living document — 
one that should be updated as your goals and interests change. 


Contribution graph 


The contribution graph is a grid of squares 7 squares high and 52 squares in length 
representing each day of the past year. Each square is filled in with a color that 
represents your contribution level on that day. If you didn’t make any contribu- 
tions, the square remains gray. If you made some contributions, the square ranges 
from light green to dark green, depending on how many contributions you made. 


Issues and pull requests count as contributions on standalone repositories. Com- 
mits to a standalone repository’s default branch (typically master ) or to its GitHub 
pages branch (typically gh-pages) count toward your contribution graph. 


If you fork a repository, an Issues tab won’t appear at the top of the repo because, 
typically, the goal of a forked repository is to contribute back to the original open 
source project. You fork the repository, make your changes, and open a pull 
request that targets the original repository. If you really want to have issues in a 
forked repository, you can turn them on in the Settings tab, though we don’t rec- 
ommend it as you should be tracking your progress on an issue in the original 
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WARNING 


repository. Because the intended behavior of a fork is to contribute back to the 
original repository, issues on the forked repository and pull requests that do not 
target the original repository do not count toward your contribution graph. The 
thought here is that you haven’t yet contributed to the main project, the fork is 
kind of just like your own private branch and the true contribution is made after 
you’ve added thoughts to an issue or merged code in on the original repository. 


The contribution graph is one of GitHub’s more controversial features. Two com- 
mon concerns are raised. The first is that it promotes unhealthy behavior in that 
many people attempt to keep long streaks of activity going. Many people take 
pride in having activity on every single day of their graph, even weekends. Though 
you may be working on something that makes you happy on the weekends, which 
is okay, it’s also very important to recognize that it’s not — and shouldn’t be — 
expected that you are coding every single day of your life. Some of the most 
important aha! moments have come from taking a break and gaining a new 
perspective. 


The other concern is that other people draw bad conclusions about a person’s 
ability as a developer based on the activity graph. For example, someone may look 
at a developer’s contribution graph, see very little activity, and conclude that he’s 
not very productive. 


Drawing any conclusions from other people’s contribution graphs doesn’t make 
sense. A contribution graph should be useful only to yourself as a fun way to see 
your history of activity. For one thing, the contribution graph is easily gamed. In 
fact, a repository provides code for doing pixel art using your contribution graph 
at https: //github.com/nikhilweee/github-activity-art. It’d be easy to use 
that tool to make your contribution graph completely dark green. The contribu- 
tion graph isn’t meant to be used as a definitive productivity metric. 


Also, contributions to private repositories may not be showing up in a contribu- 
tion graph. Click Contribution settings to change that setting. Figure 16-4 shows 
an example of both enabling the display of private contributions as well as an 
activity graph. 


Unlike the contribution graph, which shows how much activity you have, the 
activity graph shows where your activity occurs. As you can see in Figure 16-4, 
one of the authors of this book has most of his activity in commits and pull 
requests. 
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FIGURE 16-4: 
Displaying private 
contributions and 
the activity graph. 


WARNING 





2,386 contributions in the last year Contribution settings ~ 


v Private contributions 
Turning off private contributions will show only 
public activity on your profile. 





v Activity overview 
Turning off the activity overview will hide the 


Learn how we count contributions. 


section on your profile. 


[290] @semver @github © @PlasticSCM More 


Activity overview 


Code review 
B Contributed to 
Haacked/haacked.com, 
Haacked/haacked.com-DRAFTS, R 
Commits Issues 

Haacked/haacked.com-STAGE 
and 5 other repositories 

Pull requests 








Contribution activity 


Underneath the contribution graph (not shown in Figure 16-1) is the contribution 
activity timeline. This timeline of your activity on GitHub goes all the way back to 
your first commit. It can be nostalgic to go back to the beginning of your activity. 


In some cases, you may have activity in your timeline that shows up before you 
joined GitHub. You may even have activity that occurred before GitHub was cre- 
ated! How is that possible? The activity timeline includes Git activity in your 
repositories based on the timestamp of the Git commits. It’s possible to import a 
repository into GitHub that was created before GitHub existed, which would cause 
you to have activity prior to GitHub’s creation. 


Starring Repositories 


TIP 


When you visit a useful repository, you can star it by clicking the star in the top 
right corner of the repository page. A star is not only a compliment to the reposi- 
tory owner, but also serves as a bookmark of sorts for the repository. 


On your profile page, click the Stars tab to see a list of all the repositories that 
you’ve starred. This list is viewable by others who happen upon your profile page. 
Exploring the repositories others have starred is a great way of discovering 
interesting new projects. 
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TIP 


FIGURE 16-5: 
Profile 
visualization for 
one of the 
authors. 


If you’re curious about which repositories have the most stars on GitHub, use 
GitHub search (https://git.io/fhdkx) to sort users by follower count. This 
shortened URL shows the top starred repositories on GitHub. 


You may be curious about which of your repositories have the most stars. Right 
now, you can’t list your repositories in order of stars. However, one of the author’s 
visualization website at https://profile-summary-—for-github.com/user/ 
haacked provides a nice visualization of your profile and includes which of your 
repositories have the most stars (see Figure 16-5). Just replace the username 
haacked with your own to see your profile. 
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Following Users 


When you visit the GitHub profile of another user, a big Follow button appears 
underneath the profile picture. Click the Follow button to subscribe to notifica- 
tions about the user’s activity in your dashboard at https: //github.com. Who 
you follow also feeds into GitHub’s recommendation system. For example, if 
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someone you follow stars a public repository, that repository may show up in the 
Discover repositories section of your dashboard as a recommendation. 


You can see all the users you follow by clicking the Following tab of your home 
page. You can see all the people that follow you by clicking the Followers tab. 


If you’re curious about who are the most followed people on GitHub, you can use 
GitHub search (https://git.io/fh7P7) to sort users by follower count. This 
shortened URL shows the top followed people on GitHub. It may come as no sur- 
prise that Linus Torvalds, the creator of Linux and Git, is the most followed person 
on GitHub. 
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IN THIS CHAPTER 


» Growing your career through events 





» Finding an event in your area 


» Speaking at events 


Chapter 17 
Attending Events 


tarting a career as a software developer is very challenging, especially if you 

do it on your own. This is one reason why GitHub is such an essential tool for 

software developers. As the biggest source code host in the world, it’s also 
the biggest software developer community. By participating in GitHub, you 
become connected to the world’s experts and best teachers for any technology you 
may be interested in. 


Most people who use GitHub barely scratch the surface of what GitHub offers. By 
reading this book, you’re a step ahead of many other developers. The knowledge 
of how to use GitHub will serve you well. But writing code on GitHub only scratches 
the surface of a rewarding career as a developer. 


In this chapter, we look at how to get two steps ahead in your career by encourag- 
ing you to step away from the keyboard for a moment and meet with other devel- 
opers in-person. Attending events is a great way make connections that will 
benefit you during your entire career. And speaking at events is a great way to 
grow in your career even more. It may feel daunting, but everyone has something 
to offer others, even those just starting out. 
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Many kinds of events focus on software developers. They range from the informal 
meet-up or user group to the structured multiday international software confer- 
ence. In this section, we cover the most common types of events and what to 
expect at each. 


Meet-ups and user groups 


A meet-up or user group is an informal gathering of developers to cover a topic. 
Many are scheduled monthly and hosted by a local company or software interest 


group. 


These events tend to be a great way to dip your toe into software developer events. 
They tend to be small gatherings of people in your area. Each month features a 
local speaker who talks about a topic relevant to the group. (Some user groups and 
meet-ups bring in speakers from outside on occasion, but typically they focus on 
highlighting local speakers.) 


Meetups.com is a great way to find a meet-up relevant to your interests. For a list 
of JavaScript meet-ups in Seattle Washington, go to https: //www.meetup.com/ 
topics/javascript/us/wa/seattle. You can search for meet-ups by location on 
meetups.com. 


A few examples of local meet-ups include 


>> Brooklyn JS: http: //brooklynjs.com in Brooklyn, New York 
>> .NET São Paulo: www. meetup . com/dotnet-Sao-Paulo in São Paulo, Brazil 


>> SD Ruby: www.sdruby .org in San Diego, California 


Regional conferences 


A regional conference is a relatively small conference where speakers and attendees 
outside of the local area are welcome, but the focus of the conference is to provide 
a venue for local developers and speakers to connect and present their work. 


Often these conferences are one or two days. Many will have a single track of talks, 
or two at most. They’re a step up in size and structure from a meet-up and typi- 
cally occur once a year, as opposed to monthly. 
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Some of them often offer workshops either before or after the conference. These 
workshops usually cost extra, but offer more in-depth training for a specific skill- 
set or technology. For example, you can often find a full-day workshop dedicated 
to improving your Git skills. If you can afford it and find one that teaches a skill 
you want to improve, workshops are often worth the investment. 


Some great examples of local conferences include 


>> .NET Fringe: http: //dotnet fringe. org in Portland, Oregon 
>> JSConf Hawaii: www. jsconfhi .com in Honolulu, Hawaii 


>> GoRuCo: http: //goruco.com in New York, New York 


Hackathons 


A hackathon is very different from a conference. While conferences focus more on 
having speakers teach a topic through a talk, hackathons focus on building. 
A hackathon is an event that may last several days where groups of people form 
teams to work together collaboratively write code to solve some sort of problem. 


The usual format is some sort of problem is presented and teams are tasked with 
building a solution. The technology stack they may use is often dependent on the 
focus of a hackathon. For example, a mobile development hackathon will require 
that attendees build a mobile app to solve the problem. 


Hackathon is a portmanteau of the words hack and marathon. Many take the mar- 
athon aspect to the extreme by having teams work around the clock with very 
little sleep. Others try to create a balance of working hours and sleeping hours by 
forcing contestants to leave the workspace. 


Hackathons are often very inclusive of beginners. For example, www.sdhacks. io 
is open to any high school or college student in the world who is 18 or older. You 
don’t always have to have a team when you sign up for a hackathon. Often, you 
can find one when you get there. It’s best to check out the FAQ for the specific 
hackathon to learn more about the details. 


One of the largest, worldwide hackathons is targeted to college students. It’s the 
Microsoft Imagine Cup (https: //imaginecup.microsoft .com/en-us/Events?id=@). 
Winners of the Imagine Cup can win mentorship from Satya Nadella (Microsoft 
CEO), travel to the world championship, and receive Azure grants and $100,000. 


Attending hackathons can be a great way to be introduced to a new technology. 
The goal isn’t to design and implement a final product, but rather to hack together 
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bits and pieces to make progress on an idea that you have. The end product should 
look more like a prototype than a polished application. Often times, hackathons 
will have mentors that know a particular technology that you can learn from. 
Think of a hackathon as a dedicated time and place to experiment and learn. 


Though attending a formal hackathon will provide you with mentors, a space, and 

sometimes prizes, you can also always get together with friends to do one on your 

own, too! Just pick a time, place, and goal and try to hack together a prototype of 
TIP an idea you have! It doesn’t hurt to give it a shot! 


Major conferences 


A major conference tends to be large and draw attendees from all over the country, 
if not the world. Attendee counts tend to be in the thousands. Attending one of 
these conferences requires a bit more up-front planning. It’s not just arranging 
your flight and hotel. These conferences tend to have many tracks, so for any 
given time slot, you may have to choose which talk you want to see from five or 
more talks at the same time. 


Like a regional conference, major conferences often offer an array of workshop 
offerings before or after the conference. In addition to workshops, many also 
include hands on labs during the conference. Labs are usually included in the price 
of the conference and offer a great chance to actually try out the technologies 
you’re hearing about at the conference. 


Many of these conferences are thrown by large technology companies, such as 
Microsoft’s Build conference and Apple’s WWDC. 


A few examples include 


>> Oscon: https: //conferences.oreilly.com/oscon/oscon-or in 
Portland, Oregon 


>> Build: www.microsoft.com/en-us/build (location changes each year) 


>> WWDC: https: //developer.apple.com/wwdc in San Francisco, California 


Knowing What to Expect at Events 


Events can vary widely in terms of what to expect, but they all have a few com- 
monalities. The most obvious thing to expect is that other developers will be there. 
Not everyone has the benefit of living in a tech hub. If you live outside of a tech 
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hub, being a developer can feel solitary. If you work at a company that is not pri- 
marily focused on software, it can feel lonely. A software event is an opportunity 
to meet likeminded individuals — people who really care about the craft of soft- 
ware and improving themselves. Events are a good chance to make connections. 


Keynotes 


Many conferences, especially the larger ones, will include a keynote talk. Some 
include more than one. A keynote talk sets the tone for a conference and is usually 
related to the theme of a conference. For a multitrack conference, no other talks 
are usually scheduled during the keynote. 


For a major conference held by a large software company such as Microsoft or 
Apple, the keynote is where they’ll often make major announcements of new 
products and features. 


Conference session tracks 


The primary draw of conferences are the session tracks. A track is a set of talks, 
typically organized around a theme. Smaller conferences may have only a single 
track, while larger conferences may have a large number of tracks. A user group 
meeting or a meet-up may only have a single talk. 


Depending on a conference, a session can range from 30 minutes to 75 minutes. 
Many of them end with some time for audience questions and answers (Q&A). 


If you participate in a Q&A, it’s considered rude to simply use that time to make a 
statement. Make sure that your question actually ends with a question mark. 


Sometimes presenters will ask to follow up with you after the talk to have a more 
in-depth conversation. Don’t assume that it’s because they don’t want to answer 
in a public forum. Typically, Q&A lasts only 5 to 15 minutes, and there isn’t always 
enough time to fully understand a question and formulate an effective answer. 
You can meet up with presenters directly after the talk (though you should let 
them at least get their laptop and things off the stage) or ask when they may be 
able to grab a cup of coffee during the conference if it’s a multiday conference. You 
can also ask whether there is an asynchronous way to follow up with them that 
they would prefer. 


Conference presenters are typically attending the conference to learn something 
as well; they aren’t only there to present, so be respectful of their time as well. 
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Hallway tracks 


At most conferences, the sessions are very valuable if it’s a topic you want to learn 
about, but just as valuable is what’s known as the hallway track. The hallway track 
isn’t one you typically find on the conference schedule. It’s a term that people 
coined to refer to the informal conversations you have in the hallway in between 
sessions, during lunch, or when you skip a session. 


Sometimes you’ll come across a world expert in a topic having a casual conversa- 
tion with a few attendees, and you’ll be welcomed to join in. These hallway tracks 
can often be even more educational than attending a talk because you can engage 
in a conversation instead of just listening. They also may lead to lifelong friend- 
ships and interesting collaborations. 


Meeting new people at a conference can be intimidating, especially if you’re an 
introvert. It may help to know that most people feel this way. If you draw up the 
courage to introduce yourself to someone you don’t know who is alone, she may 
feel relieved. If you’re an extrovert, look for opportunities to draw people who are 
alone into a conversation in a low-pressure manner. 


After-hour conference events 


Many conferences include after-hour events. Some of these events can be quite 
lavish depending on the size of the conference. 


Often, these events include loud music and alcohol, so be aware if that’s not your 
thing. 


Many conferences try to be more creative and inclusive with their attendee events. 
For example, one conference rented out a table tennis place with a large number 
of tables. 


A respectful professional environment 


At most events, you can expect a respectful, inclusive, and professional environ- 
ment. This environment is conducive to networking, socializing, and learning. 


There have been cases where conferences failed to live up to that expectation. 
Because of that, many conferences now adopt and enforce a code of conduct. 
A code of conduct outlines behavioral expectations of the participants in a confer- 
ence. More importantly, it communicates to folks who are often the targets of 
harassment that the conference takes harassment seriously and is not welcome at 
the event. 
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Becoming Familiar with GitHub Events 


Given that this book is about GitHub, we’d be remiss not to include some informa- 
tion about GitHub’s own events. GitHub hosts and sponsors several conferences 
throughout the year. 


To see which of these events are upcoming, you can visit https: //github.com/ 
events. This page lists GitHub’s own upcoming events, as well as events that it 
sponsors. 


GitHub Universe 


GitHub Universe (https: //githubuniverse.com/) is the flagship conference for 
GitHub. It is held yearly in the city where GitHub’s main headquarters resides, San 
Francisco, California. The conference is usually held in the fall around October or 
November. 


As GitHub describes it, 


GitHub Universe is a conference for the builders, planners, and leaders 
defining the future of software. 


This conference is where GitHub typically makes its biggest announcements of 
the year during the keynotes. It attracts well-known speakers from prominent 
software companies. 


In 2018, the conference had around 1,800 attendees who attended three tracks of 


talks. The cost of the conference is reasonable, around $99 per person, or $199 if 
you also attend the workshops. 


GitHub Satellite 


The GitHub Satellite conferences (https: //githubsatellite.com/) are an off- 
shoot of GitHub Universe. They bring a GitHub universe-style conference to loca- 
tions around the world. 


Held once a year, past Satellites have been held in places such as Berlin, Tokyo, 
and London. 
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GitHub Constellation 


GitHub Constellation (https: //githubconstellation.com/) is a series of small 
community events held multiple times a year around the world. These events 
focus on the local community and often feature speakers local to the area. They 
are typically free and occur over one or two evenings. They’re not all-day confer- 
ences like Satellite and Universe. 


Git Merge 


Git Merge (https: //git-merge.com/), is a conference sponsored by GitHub, but 
focused on the Git version control tool and the people who use it every day. As 
GitHub puts it, 


Through technical sessions and hands-on workshops, developers and teams of 
all experience levels will find new ways to use, build on, and scale Git. 


The conference features a preconference hands-on day of workshops focused on a 
range of Git topics. This conference is a great one to learn more about Git and to 
improve your Git skills. 


Speaking at Events 
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A lot of developers have the misconception that speaking at conferences is only for 
experts who have been in the industry for years or that only big extroverted per- 
sonalities speak at conferences. We’re here to tell you this is not true. 


Everyone has a Story to tell 


Whether you realize it, somewhere inside of you, you have an interesting story to 
tell — even if you’re relatively new as a software developer. One thing all these 
events have in common is they’re better off when they have a diverse set of speak- 
ers with diverse viewpoints. For example, it’s common for experienced developers 
to lose their “beginner’s mind” when working with a technology for so long. 
A talk by a beginner about their struggle to learn a particular technology is often 
eye-opening and just the kick in the pants experienced developers need to make 
it better. 
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Benefits of being a speaker 


Being a speaker offers a lot of benefits. The main one is that it’s a forcing function 
to spend time deeply learning a topic. If you plan to give a talk on a subject, it’s a 
good idea to research it beyond what you already know. And teaching a topic to 
others is a great way to solidify your own understanding. 


Not only that, it’s a great way to receive feedback on your ideas. Often, after giving 
a talk, someone will have a unique insight to share that improves upon your ideas. 
You wouldn’t have received that feedback without putting your ideas out there. 


Another benefit is the exposure and networking opportunities that being a speaker 
entails. Because your badge will have the word SPEAKER on it, people are more 
likely to want to meet you and talk to you. When you’ve spoken at a few confer- 
ences, it gets your name out there. When you apply for a new job, people may give 
you more opportunities because they’ve heard you speak. 


And a few perks come with being a speaker. Often, conferences have special 
speaker-only events where speakers can get to know each other. This event often 
leads to a great networking opportunities and friendships because it’s easier to 
remember people in a smaller setting. Also, as you speak at more and more con- 
ferences, you may see some speakers at multiple conferences and even become 
friends. It helps when you go to a conference to already know some of the other 
people there because you’ve spoken together before. 


Finding Funding for Events 


Some of these events and conferences can get expensive. Microsoft BUILD can cost 
upwards of $2,500, and Google I/O is close to $1,200 — not to mention the trans- 
portation and parking to get to the conference and the hotel and flight costs if you 
don’t live near the venue. 


Many software companies will pay to have employees attend a conference if the 
conference is a valuable learning opportunity. If you work for a software company, 
it doesn’t hurt to ask. To make your case stronger, explain how the things you 
learn at the conference will improve your performance at work. 


Larger software companies may also be sponsoring events and need volunteers to 


attend and help run the booth. Some companies even offer a stipend for attending 
conferences as a perk and part of your compensation package. 
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Another way to fund your trip is to apply for a scholarship. The Grace Hopper 
Celebration is a large conference with more than 18,000 attendees and celebrates 
women in computing. With technical tracks as well as tracks focused on diversity 
and inclusion, this conference is typically held over three days and moves around 
the United States for the venue. The Anita Borg institute that puts on the confer- 
ence also offers scholarships that you can find at https://ghc.anitab.org/ 
2019-student-academic/scholarships. These scholarships typically include 
airfare, hotel, transportation costs, meals, and a ticket to attend. They focus on 
students and faculty for this particular scholarship. 


Most conferences will waive the price of the conference ticket for speakers. Many 
conferences will also cover hotel and travel to the conference. And some confer- 
ences will even offer an honorarium on top of expenses. These benefits completely 
depend on the conference. Furthermore, some conferences ask for volunteers to 
help run the conference, which also tends to come with some perks like a free 
ticket so that you can enjoy the rest of the conference when you’re not working 
one of your shifts. The Grace Hopper Celebration calls it the Hopper Program, 
which you can find at https: //ghc.anitab.org/hoppers. 


If you’ve found an event you’re particularly excited to attend, before you shell out 
the thousands of dollars from your own pocket, ask around! Ask your network if 
anyone knows of any scholarships, apply to be a speaker or volunteer, and ask 
your company or school what resources are available to you! 
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The Parts of Tens 


IN THIS PART... 


Find resources on GitHub.com to support your growth. 


Discover how to keep up-to-date with GitHub 
Integrations. 


Explore external resources for learning more about 
collaborative coding. 


Understand techniques to improve your workflow on 
GitHub.com. 


Find tools that will help improve your workflow. 


Become an effective community member with 
guided tips. 


IN THIS CHAPTER 


» Finding resources on GitHub.com 





» Exploring online resources in the 
broader web 


» Keeping informed about GitHub 
integrations 


Chapter 18 


Ten Ways to Level Up 
on GitHub 


ecoming an expert on GitHub is not a quick task. First, you need to master 

a lot of specific features of GitHub. Knowing how to create a pull request or 

link issues to a project board with automation for effective project manage- 
ment is one aspect of this expertise. 


It is also important to begin to master specific areas in software engineering as a 
whole to be able to effectively contribute to projects in meaningful ways. Further- 
more, becoming an effective community member is another way to become a 
GitHub expert. 


This chapter briefly describes ten ways you can level up in each of these areas so 
that you can be successful on GitHub. 


Trial and Error 


One the best ways to learn anything is to just try. When you try, you always learn. 
If you try and fail, you learn what not to do and gain insight into how something 
works. When you succeed, you learn what to do next time! Learning how to use 

TIP GitHub and how to code is no different. In fact, learning by trial and error in the 
tech field is even easier. 
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GitHub provides you with unlimited public and private repositories, which means 
you can try all kinds of things without ever spending a dollar! We highly recom- 
mend getting onto GitHub.com and creating a new repository. From there, make a 
README . md file that you can easily modify and work with. This is the “Hello World” 
app of a GitHub repo. You can create issues and pull requests that modify the 
README . md file just to see how they work. 


To learn more about collaboration on GitHub, invite your friends to be collaborators 
on your repo or make your repo public and send them the link to it. Ask them to 
comment on issues and create and review pull requests. Ask your friends to make 
their own public and private repo where you’re a collaborator so that you can try 
all the GitHub features from the perspective of a contributor. There is no harm in 
trying things out. 


After you finish exploring, you can always delete the repositories, if you want. 
keeping some around may be useful for the inevitable time when GitHub releases 
new features that you want to try on a dummy repo. 


GitHub Help Docs 
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The GitHub help docs are extensive and detailed. You can find them by going to 
https://help.github.com. The help docs can be extremely useful if you know 
exactly what you want to get done. With 38 categories that each have anywhere 
from 1 to 70 docs, hundreds of pages describe every single feature of GitHub with 
images and cross referenced links. 


At the top of the GitHub Help page (where all the docs are located) is a search bar 
where you can type a query, and docs related to that query will appear. Similar to 
Google, as you start typing your query, results will start to appear. If you press 
Enter or click the magnifying glass button, a page with search results appears. On 
this page is a notation next to the doc title with the category that it is a part of. We 
recommend paying attention to that notation because it will help you better nav- 
igate docs in the future. If you understand how GitHub categorizes the docs, you 
may be able to find what you’re looking for faster next time. 


If you click a specific doc, you see the documentation page. On the right side of 
this page is a list of Article versions. The documentation defaults to GitHub.com 
documentation, but GitHub also offers a slightly different version to enterprise 
users. Clicking on the different article versions displays the docs specific to that 
version of GitHub, ensuring that you have the most accurate information. 
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Extremely security conscious companies are more likely to use GitHub Enterprise, 
as it allows them to have the interface and functionality of GitHub while keeping 
their code and data secure on their own servers. This ability can be important if 
you have proprietary code that you don’t want anyone, not even GitHub, to have 
access to. If you’re planning on open sourcing your code (which a lot of large 
companies, like Microsoft, do a lot of) or you just want your code to be private 
from the world, storing on GitHub.com is typically good enough. 


At the bottom of each documentation page you will typically find a section called 
Further reading. This section lists documentation pages that may be relevant to 
what you’re trying to do. Below this section is a button that says Contact a human. 
If the documentation isn’t helping you resolve your issue, click this button to go 
to a page where you can contact GitHub. The Contact page has an extensive list of 
all the ways you can try to help yourself first, but then provides a quick and easy 
message section for you to ask a question. On the left side of the contact page you 
can also find other reasons for contacting GitHub, such as reporting abuse, report- 
ing content that isn’t appropriate, reporting copyright infringement, privacy con- 
cerns, and portals for both premium and enterprise support, if you’ve purchased 
those plans. You can also directly access this page at https://github.com/ 
contact. 


This Contact page is not where you should submit a question or concern about a 
specific repository unless you’re reporting abuse, content, or copyright infringe- 
ment. If you have a problem getting code to run or have a question about a specific 
repository, you should ask in an issue directly on that repository home page on 
GitHub. 


At the top of the GitHub Help page is a drop-down list where you can select which 
version of GitHub you’re interested in looking at the documentation for. This 
selection defaults all the docs to that version so that you don’t have to change it 
every time you visit a page. There is also a quick link to the Contact page and a 
quick link to return to the GitHub home page. 


Docs are your friend. There is a lot to learn and software changes quickly; expert 
programmers are experts not just because they know a lot, but mostly because 
they know how to figure something out — and that often means knowing how to 
find information. 


An alternative to the docs is the GitHub Guides found at https: //guides.github. 
com. These visual, quick five to ten minute guides explain a specific action you can 
take in GitHub — for example, how to fork a project. These guides are great 
reminders for how to do something and provide a bit more insight than the 
documentation page for a specific feature. 
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GitHub has invested in a team of folks dedicated to helping novices learn how to 
use GitHub. And though documentation can help when you know exactly what 
you’re looking for, sometimes it can be hard to follow still images. That’s why 
GitHub brings you Learning Labs, which are absolutely incredible. Learning Labs 
are step-by-step, guided tutorials where you actually create a real repository on 
GitHub and perform real actions that you would normally. The friendly GitHub 
Learning Lab Bot guides you through the tutorial, creating pull requests for you to 
review or issues for you to close out. 


To get started with the Learning Labs, go to https: //lab.github.com and click 
the blue Sign in with GitHub button. Now you can browse a number of courses that 
may be useful for you to get an in-depth introduction into everything GitHub. 


On the Courses page, at https: //lab.github.comcourses, you can find 14 (maybe 
more by the time you read this book) courses categorized into topics such as Git, 
GitHub, and Open Source. With some of the most commonly used features on 
GitHub being highlighted, you can learn to review pull requests, manage merge 
conflicts, and make your open source project stand out among the millions of 
projects on GitHub.com. 


Clicking on a course takes you to a detailed page where you can learn more about 
that course and join it. Often times, the Learning Lab will want to create a public 
repository on your account. Don’t worry; you can always delete it after you’ve fin- 
ished the course, but there is also nothing wrong with showing the world that you 
take learning seriously. You will also be asked to accept the Terms and Conditions 
and to install the Learning Labs app onto your account. This app installs only on 
the repos you select, so you can have it install on the repo that it creates as part of 
the course. For example, doing the merge conflict course, you may give it access 
only to the merge-conflict repo that it creates, as shown in Figure 18-1. 


After you install the Learning Lab app, return to the Learning Lab course page 
(for example, https: //lab.github.com/instal1 ?org=githubtraining&course= 
managing-merge-conflicts) and click the Done installed? Move on link under 
the green Install button. You’re taken to a new page with each of the course steps. 
The course overview page is useful because you can always stop in the middle of 
the course and pick it up later if you aren’t able to finish in one sitting. 


A typical Learning Lab will have the bot open an issue in the repo that it created 
with a description of what you should do. All you have to do is read through the 
issue and follow the instructions! 
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FIGURE 18-1: 
Giving the GitHub 
Learning Lab app 

access toa 
specific 
repository. 
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GitHub 





Permissions 


v Write access to code 
v Read access to metadata and repository hooks 


v Read and write access to administration, commit statuses, deployments, issues, pages, pull requests, and 
repository projects 


Repository access 


All repositories 
This applies to all current and future repositories 


© Only select repositories Select at least one repository 
QO select repositories ~ 


Selected 1 repository 


E sguthals/merge-conflict |Suggested) x 





Approve and install Cancel 





We recommend opening the repo in a new tab so that you can refer back to the 
instructions without losing your place in what you’re trying to accomplish. 


When you’re just starting to get introduced to GitHub, Learning Labs is a great 
way to experiment with features and learn specific workflows. It’s essentially trial 
and error, but with a helpful guide. 


In-Person Training 


GitHub is tool for more than 30 million developers and over 2 million organiza- 
tions. From novice coders just learning to create their first GitHub Pages website 
in Markdown to Microsoft bringing you VS Code, GitHub’s goal is to support more 
people building more software. As such, GitHub offers trainings where a GitHub 
expert will help better equip your team to use GitHub. 


With eight different focus areas, plus a customized training in case you need 
something different for your team, GitHub will not only guide you through the 


CHAPTER 18 Ten Ways to Level Up on GitHub 301 


details on how to use GitHub, but will engage everyone in the fundamental work- 
flows and techniques to using it effectively. The focus areas are 


>> Workflow consultation 
>> Implementation 

>> Admin mentoring 

>> Train-the-Trainer 

>> Migration 

>> API consultation 

>> InnerSource 


>> Services account engineering 


For a full description of each of these areas, as well as what you can get with a 
customized course, visit https: //services.github.com. This service is not free. 
You can submit an inquiry and a GitHub representative will reach out with more 
information about costs. 


If you’re a novice, you may not need the full-force of a GitHub trainer. However, 
it may be something for you to suggest to your company if it’s asking you to 
switch over to using GitHub. In-person training can also be useful if you start a 
company and want everyone on your team to not only use the tool, but to use it 
effectively. 


Project-Specific Documentation 
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One of the best ways to learn about a specific open source community and a spe- 
cific technology is to reach the project-specific documentation. When you are both 
new to GitHub and new to a technology, it can be effective to read through the 
documentation most relevant to your interest and to explore the behaviors of 
other members of the community by reading through issues and pull requests. 


The VS Code project is a good example of a project with good documentation and 
enough community engagement to understand behaviors. If you go to https: // 
github .com/microsoft/vscode, you can find a well-written README with links to 
where you can submit bugs and feature requests, how to contribute to the project, 
and where to engage with the core developers. 
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REMEMBER 


FIGURE 18-2: 
Effective pull 
request review 
feedback on the 
VS Code open 
source project. 


When you’re first starting to learn, following the How to Contribute documenta- 
tion (for example, VS Code has a wiki page for it at https://github.com/ 
Microsoft/vscode/wiki/How-to-Contribute) can help you get your code up and 
running on your local machine. Even if you don’t end up contributing directly to 
the project, following this documentation can be a good learning exercise. 


Some projects are strict on their style and contributing guidelines. For example, 
the VS Code project has guidelines on style found at https://github.com/ 
Microsoft/vscode/wiki/Coding-Guidelines. Having code that is consistent in 
style means that errors are less likely to occur. For example, if you always use 
PascalCase for type names and camelCase for function names, you can quickly 
identify when someone accidentally referred to a type instead of a function in 
their code. 


It is also important to know the requirements for contributing code to the open 
source project. For example, on VS Code, you must first sign a Contributor License 
Agreement before you open a pull request on the repository. 


Looking through open and closed pull requests can also be good practice when 
you’re trying to learn about the specific community. Understanding what kinds of 
errors are common in the particular code base or what kinds of changes the core 
team typically requests can help you learn about the technology as well as the 
specific project. Successful open source projects will have pull request reviews 
with substantial information. For example, on one of the pull requests for the VS 
Code project, you can see user ramya-rao-a not only let user grunxen know that 
alerts shouldn’t happen, but also provides a suggestion on how to fix this bit of 
code, as shown in Figure 18-2. 





src/vs/workbench/parts/extensions/electron-browser/extensionsViewlet.ts Outdated 


return this.progress(Promise.all(this.panels.map(view => { 
(<ExtensionsListView>view) . show(this.normalizedQuery()).then(model 


+ return (<ExtensionsListView>view).show(value, token).then(model => 


A ramya-rao-a on Nov 5, 2018 Member 
When search is cancelled, we shouldnt be alerting the search result, as is done below. 


| would suggest to update the show function to return null when search is cancelled. 
Then add a null check on the model before running alertSearchResult 


grunxen on Nov 6, 2018 Author 


ExtensionsListView#show now returns null if search was canceled 


Reply... 
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External Community Places 


Some open source projects have places other than GitHub where more general 
conversations can happen. These places can be a really great way to learn without 
having to explicitly open an issue or pull request. You can find these extended 
communities many places online, some with a more interactive community while 
others are more feedback-driven. 


The VS Code project, for example, calls out the StackOver flow questions that are 
tagged with visual-studio-code. If you have questions about VS Code, it’s best that 
you first search the questions already asked. If yours is unique, make sure you use 
the appropriate tag when writing it. 


This project also suggests giving feedback on Twitter, asking questions or directly 
giving feedback to the @code alias. Giving feedback is also a good way to get 
updates on the project. 


The Atom project, on the other hand, has a specific forum run on its website found 
at https: //discuss.atom. io. This forum is a great place to search for answers to 
your question or ask a unique one, if it hasn’t been asked. As you become more 
expert in using Atom, you can start contributing answers. 


Atom also has a public Slack that you can join. Just visit http: //atom-slack. 
herokuapp.com and enter your email address. You will be sent an invitation to join 
the public Slack channel where you can ask questions and generally follow the 
discussion around Atom, Electron, or just general chat “around the water cooler”. 
This resource is great if you’re learning on your own. A Slack channel can be a 
virtual office where you have colleagues and peers that you can ask questions to in 
a lightweight manner (for example, not open an issue on GitHub). 


Online Coding Tutorials 
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Depending on what you’re trying to learn and contribute to on GitHub, an online 
coding tutorial may be right for you. Now, you can probably find thousands of 
coding tutorials online from a random person posting a blog to a YouTube video 
showing you exactly how to do something, but some of our favorite coding tutori- 
als offer you an in-browser sandbox where you actually get to try out the code it’s 
trying to teach you about. 


When dealing with GitHub, you may be inclined to learn a bit of Ruby. If you ever 
want to create a GitHub app or integration, it may behoove you to know a bit about 
Ruby to make your life easier because GitHub is built using Ruby. The online 
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tutorial https: //ruby.github.io/TryRuby gives you a step-by-step guide with 
an editor and an output window right in your browser. 


While the Ruby tutorial gives you a handy Copy button so that you don’t have to 

type all the example code every time, it can be useful to go through the motions of 

typing to slow down and better learn what you’re reading. We recommend typing 
warning the code, even if it seems simple enough, so that you get more practice. 


If you’re making a web application, you may want to get some practice with 
JavaScript, HTML, and CSS. https: //jsfiddle.net is a great place to start, giv- 
ing you an editor for each language along with an output window. It has also been 
enhanced to have boilerplate starter code for commonly used languages, such as 
React, TypeScript, and CoffeeScript. 


Another interactive sandbox tutorial website that we particularly like is the Try 
.NET site at https://dotnet.microsoft.com/platform/try-dotnet. Before 
diving in to the intricacies of the .NET Framework, you can get your hands dirty in 
a safe environment right in your web browser. With snippets that you can try, 
tutorials you can follow, or simply an open playground to experiment, this site 
can offer you support at any stage in your career. 


While you can definitely find other sites where you can code in the browser, these 
are just a few of our favorites. When you’re first starting to learn a new language 
or framework, we recommend you explore various resources or ask for recom- 
mendations from peers or communities you’re interested in joining before just 
following the first tutorial you find. 


Online Courses and Tutorials 


Online courses are becoming more popular with the development of better tools 
for engaging with learners. Two of the largest platforms for online courses are 
Coursera and EdX. These platforms partner with universities and large companies 
to provide in-depth education and sometimes certification or even degrees. 


Both Coursera and EdX offer specializations with multiple courses. For example, 
there is a Ruby on Rails Web Development Specialization on Coursera that was 
created by Johns Hopkins University. Meanwhile, Microsoft offers a professional 
certificate in Introduction to Computer Science, which has three courses. 


Furthermore, some universities offer degrees, such as the University of London 


and its bachelor of science in computer science degree on Coursera or University 
of California, San Diego’s MicroMasters in data science on EdX. These programs 
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often require an application and admission into the specific program — not just 
anyone can join. 


For more lightweight options, sites like Udemy and Pluralsight offer more than 
100,000 online courses at low prices or sometimes even free. These courses tend 
to be more focused on video lectures and tutorials rather than extensive course- 
work, but they’re really great options for when you’re first getting started and just 
want to get an introduction into something. 


Khan Academy is another great place to find always free courses. Khan Academy 
supports learners as young as two on its Khan Academy Kids app (https://www. 
khanacademy.org/kids?from=lohp) to adults looking to learn something new 
from computing to studying for the LSAT to entrepreneurship and growth mind- 
set! This great resource offers curated courses that are more lightweight than 
Coursera or EdX. 


It is also important to not forget the power of YouTube. Though videos on 
YouTube aren’t curated and aren’t held to any standards, you can find a lot of 
really amazing content. For example, The LearnCode.academy channel has a 
GitHub Tutorial for Beginners video with almost two million views. Siraj Raval is 
also a great channel to follow as he gives tutorials, but also explains the history of 
certain technologies and how they actually affect our world. 


Blogs and Twitter 
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If you’re looking for a updates on certain technologies or products or a quick 
answer to something, it can often be fruitful to follow the right people on Twitter 
and subscribe to the right blogs. We won’t be able to tell you who the right people 
are for you to follow, because each person reading this book may have different 
interests when it comes to learning and contributing on GitHub, but we can give 
you some tips! 


First, recognize that people who use Twitter and who blog are usually only repre- 
senting their own ideas and are not representing a company or being held to any 
company standards. This means that you should take what they say with a grain 
of salt and recognize that they are just people, saying what is on their mind, and 
probably also still learning and developing (as we all are always learning and 
developing). 
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When searching for Twitter accounts to follow, you can start with accounts repre- 
senting the technology you’re interested in learning about. For example, following 
@GitHub may be a good idea because this account will not only post updates to 
GitHub, but will also often highlight other tech, people, or events related that may 
be of interest to you. This will start to give you ideas on other people to follow. For 
example, GitHub recently retweeted Safia Abdalla (@captainsafia) who is a 
developer at Microsoft and is also an open source developer. She does keynotes and 
talks on open source development, too, so if you’re interested in learning more 
about open source development, she may be a good resource of information! 


Advice on which blogs to follow is similar to the advice on Twitter. We’d recom- 
mend starting with some of the blogs that may have the most relevant 
information — for example, the GitHub blog at https: //github.blog gives you 
up-to-date information about GitHub features. Another great resource is Medium. 
com, where you can search any keyword and get a number of different perspec- 
tives and pieces on it. For example, https: //medium.com/search?q=github 
results in a lot of lists of things you can do on GitHub that you may not have 
known about. It can be a great start to then looking into the GitHub docs for more 
in-depth information. Finally, you can also just Google a keyword, and various 
blogs, tutorials, and videos are likely to pop up. 


Community Forum 


TIP 


We also recommend the GitHub Community Forum. especially for getting help 
about GitHub. Found at https://github.community, this forum tends to have 
hundreds of people actively online at any given time. The GitHub community is 
worldwide, and people from all different technological backgrounds are typically 
eager and willing to help. 


Many threads contain topics specific to GitHub, such as how to use Git and GitHub, 
GitHub Pages, and the GitHub API. But this community forum offers even more 
than GitHub-specific information. As the number one place for developers, GitHub 
also provides a space for the community to learn from each other in general pro- 
gramming concepts and projects overall. 


Before participating in the GitHub Community Forum, we recommend reading 
through the Code of Conduct, found at https: //github.community/t5/Welcome/ 
Code-of-Conduct/m-p/65#M37. Just like an open source project, the community 
forum is an open place where one must remain respectful and maintain a collab- 
orative spirit.click 
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From this community forum, you can also find the GitHub Education community 
forum at https: //education.github.community focused on how to use GitHub 
in the classroom. This resource is great if you’re a student and you’d like to con- 
vince your teacher to use GitHub or if you’re a teacher looking to teach your 
students. 


The GitHub Community Forum is a great place to ask your generic questions that 
wouldn’t be appropriate to ask on a specific repository. The GitHub community is 
vast as it is a large portion of the developer community. Almost anywhere you go 
in the developer community, you are sure to find someone who can help you or at 
least point you in the right direction. The most important thing for you to remem- 
ber is to ask questions, be respectful, and remember to give back with your knowl- 
edge as you begin to learn. 
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IN THIS CHAPTER 


» Discovering software tools that 
improve your development workflow 


» Finding out how StackOverflow helps 
get your questions answered 


» Realizing that some workflow 
improvements are techniques, not 
tools 


Chapter 19 


Ten Ways to Improve 
Your Development 
Workflow 


orking on software is tedious at times. Writing code is laborious and 

requires a ton of steps and intense concentration. On top of that, a lot 

of tasks have to occur during the coding process, such as running tests, 
creating mock-ups, and tracking progress. 


Any tools and techniques you can use to help streamline and improve your devel- 
opment workflow not only saves you time, but can improve the quality of your 
work. It’s always worth spending time periodically looking at ways to improve 
your development workflow. In this chapter, we cover ten ways you can improve 
your development workflow. 


Drafting Pull Requests 


Chapter 8 discusses creating pull requests when you’ re ready to have code reviewed 
and merged into the main branch of a repository. But that’s not the only way to 
use pull requests. In fact, GitHub employees have long stated that creating a pull 
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FIGURE 19-1: 
Drafting a pull 
request. 


FIGURE 19-2: 
The ready for 
review button. 


request is the beginning of a collaborative conversation. Sometimes it may be 
appropriate to create a pull request even before you’ve pushed code. It’s possible 
to do by creating a branch on GitHub and then creating a pull request from that 
empty branch. 


Or maybe you do have some code to push, but you know it’s incomplete. You just 
want to gather some feedback on your progress without alerting code reviewers 
that they should give your pull request your full attention with a detailed code 
review. This is where draft pull requests come in handy. To draft a pull request, 
click the down arrow on the Create Pull Request button and then select Create 
Draft Pull Request, as shown in Figure 19-1. 





a Add my handle and fun fact to README 


Write Preview A B i «o FEE ONS 


Because this is what | do when | party. 


Attach files by dragging & dropping, selecting them, or pasting from the clipboard. 


ED Styling with Markdown is supported Selfie! Create Pull Request ~ 


Y Create Pull Request 
Automatically requests reviews from code 
owners 


-œ 1 commit A1 file changed Create Draft Pull Request 


Doesn't request code owners review and 
cannot be merged 





E Commits on Feb 07, 2019 











This creates a pull request in draft mode. If you have a CODEOWNERS file (which we 
cover in Chapter 11) in your repository, a draft pull request will not notify those 
reviewers until the pull request is marked as ready for review by clicking on 
the Ready for review button, as shown in Figure 19-2. 





O This pull request is still a work in progress. Ready for review 


Draft pull requests cannot be merged. 


Merge pı ast You can also open this in GitHub Desktop or view command line instructions. 
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Git Aliases 


TIP 


Chapter 6 introduces the concept of Git aliases. Git aliases are short shell scripts 
that extend Git and automate common tasks. Chapter 6 includes a Git alias for 
moving commits from one branch to another. 


Git aliases can automate tedious clean-up tasks. For example, the following alias 
deletes all branches that have already been merged into the target branch. If no 
target branch is specified, then it assumes the master branch. 


[alias] 
belean = "!f() { git branch —-merged ${1-master} | grep -v 
${1-master}$" | xargs git branch -d; }; f" 


" 


Aliases can be combined together. For example, before you clean up branches, you 
may want to switch to the target branch and update that branch from the remote 
server first. 


[alias] 
bdone = "!f() { git checkout ${i1-master} && git pull 
—-rebase && git bclean ${1-master}; }; f" 


Note how the bdone alias makes use of the bclean alias. You might use the bdone 
alias right after you push a branch that then gets merged by someone on GitHub. 
com. After the branch is merged, you can run git bdone, and the alias will switch 
you back to master, run a git pull, and then run the bclean alias. 


Adding aliases you find from elsewhere can be a pain, though. This post by one of 
the authors describes a quick way to include a bunch of aliases into your Git config 
file: https: //haacked. com/archive/2019/02/14/including-git-aliases/. 


Run Tests Automatically 


Writing automated tests for code, such as unit tests, is an essential skill for pro- 
fessional software developers. It helps improve the design of code and provides a 
safety net when making changes to code. 


When working with a code base with a lot of tests, it’s not uncommon to forget to 


run tests often. And even if you do run tests often, it’s a distinct step: Make some 
changes and then run a command to run your tests. 
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A great way to improve your development workflow is to automate the test runs. 
Many tools will automatically run tests when your code changes. Here’s a short 
list of tools for various platforms: 

>> NCrunch for .NET 

>> Guard-test for ruby 

>> Tsc-watch for TypeScript 

>> Cargo-testify for Rust 


>> Wallaby.js for JavaScript 


Many of these tools are smart about only running the tests affected by the changed 
code. That way, every change doesn’t end up running the entire test suite. 


Take Breaks 
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One simple effective method for improving your workflow, albeit one that is 
neglected by many developers, is to take regular breaks. Writing code may feel like 
a sedentary task, but any activity done over an extended period of time can put a 
lot of stress on the body. The human head is pretty heavy (some heavier than 
others). Holding it upright can put a lot of stress on the back and neck. According 
to DataHand, a maker of ergonomic keyboards: 


At the end of an average eight-hour workday, the fingers have walked 16 
miles over the keys and have expended energy equal to the lifting of 1 1/4 tons. 


Taking regular breaks to stretch your hands, arms, and back can help you remain 
healthy and thus more productive. 


However, that’s not the only benefit of taking breaks. Many people are fans of the 
Pomodoro Technique developed by Francesco Cirillo in the late 1980s. This tech- 
nique breaks work down into intervals, traditionally 25 minutes, with a short 
break of around 3 to 5 minutes in between. Each interval is known as a Pomodoro, 
Italian for tomato. Why a tomato? Apparently, Cirillo used a tomato-shape timer 
in college. 


After four pomodoros, you take a longer break (15 to 30 minutes). The benefit of 
this technique is not only to enforce that you rest your body, but it has the added 
benefit of helping you maintain focus. The general idea is that during a pomodoro, 
you are intently focused on work. You generally close all other distractions. You 
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can use some of the longer breaks to do things like check emails and browse the 
web, if you need to. But during the 25-minute pomodoro, you should be intently 
focused on work. Practitioners swear by the increased focus and flow the tech- 
nique encourages. You can find many examples of pomodoro timer applications 
on the web. 


Prototype User Interfaces 


Whether it’s a web or desktop application, building a user interface can be very 
time-consuming. And it’s difficult to know how usable an interface will be until 
you put a human in front of it to try it out. 


One tool that saves a lot of time when building an interface is a rapid prototyping 
tool, such as Balsamig or Invision. This is by no means an exhaustive list of such 
tools. 


The benefit of these tools is they make it possible to build mock-ups of a Graphical 
User Interface (GUI) in a short amount of time. Some tools even make it possible 
to add a bit of interactivity so that you can put the interface in front of a person 
and run some informal usability tests. You can get a lot of valuable feedback by 
simply asking people questions like “How would you accomplish a task on this 
screen? What would you click next?” 


if you had written a bunch of code. Once you’ve run through a few iterations with 
the mock-ups, you can build the actual GUI with more confidence that you’re on 
TIP the right track. 


Q Making changes to the interface to respond to such feedback is much faster than 


Scaffold Apps with Yeoman 


Starting a new application from scratch can be time-consuming. A lot of boiler- 
plate code goes into setting up a real production application, and the boilerplate is 
different depending on the type of app and what the app does. 


Yeoman is a tool for scaffolding modern web apps. To install it, run the following 
command: 


$ npm install -g yo 
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This command adds the yo command to your machine. Yeoman works with gen- 
erators, which are essentially plugins to the yo command, that add support for a 
given project type. A huge ecosystem of generators is out there. 


For example, suppose that you want to build an extension for Visual Studio Code 
(VS Code). You would start by installing the generator for VS Code: 


$ npm install -g yo generator—code 
To run the generator, you run the yo command with the generator name: 
$ yo code 
The generator prompts you to answer some questions about the project to gener- 


ate, such as specifying a project name. At the end, the generator takes your 
answers and scaffolds a project folder with a working VS Code extension. 


Chrome Web Developer Tools 
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If you develop browser-based applications for the web or for the Desktop via Elec- 
tron, no tool is probably more useful than the Chrome Web Developer Tools. To 
launch these tools, use the shortcut 3g + Option + I on the Mac or Ctrl + Shift + I on 
Windows. 


You can also launch the developer tools by right-clicking on an element of any 
web page and choosing the Inspect menu option. When the developer tools open, 
select that element in the Elements tab. 


The Elements tab of the developer tools allows you to explore and manipulate the 
DOM. You can also manipulate the CSS. This provides a nice way to debug CSS 
problems because it gives you instant feedback on your CSS changes. 


The Console tab lets you run JavaScript commands in the context of the current 
web page. 


The Sources tab lists all the scripts that are loaded in the context of the page. This 
list can be eye-opening when you go to a website you use often and look at this 
tab. A given web page can have a large number of scripts running. 


The Network tab shows all the network requests that were made to render the 
page, the size of the requests, how long they took, and when they happened in 
relation to each other. This information is useful for debugging issues where a 
large request is causing delays in rendering a page. 
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The Performance and Memory tabs are useful for profiling execution time and 
memory usage of a page. 


StackOverflow 


StackOverflow.com is a question and answer website for developers. Since its cre- 
ation in 2008, it’s had a huge impact on the developer community. A big part of its 
popularity is due to the gamification techniques it employs to maintain high- 
quality questions and answers. 


For example, questions and answers can be up voted and down voted. Answers 
that receive the most up votes are displayed directly under the question so that 
people who find the question later don’t have to wade through a ton of answers to 
find the best answer. If the poster of a question accepts an answer, that answer 
floats to the top (unless the poster also answered the question), regardless of the 
number of upvotes. This setup sometimes causes a situation where a better answer 
with more up votes is displayed before the accepted answer. 


Asking questions, answering them, and having questions or answers voted up all 
contribute to your reputation points. As your reputation points increase, you gain 
more privileges on StackOverflow, such as being able to edit questions and answers 
to collectively improve them like a wiki. 


If you’re stuck on a programming task, StackOverflow is often a good place to 
start searching for an answer to your question. 


Code Analysis Tools 


A wide range of tools can analyze code for potential problems and potential 
improvements. When used properly, these tools can save you a lot of time and 
headache. 


Linters are a class of tools named after a Unix utility named Lint that analyzes C 
code to flag bugs, style errors, and potential problems without having to run the 
code. While Lint is the original tool, many linting tools exist for different pro- 
gramming languages, such as JSLint for JavaScript and ruby-lint for Ruby. 


Static analysis tools are similar to linters but work against statically typed lan- 


guages. These tools take advantage of type information in the source code to find 
issues in the code that aren’t syntax errors (which the compiler would already 
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catch) but may cause problems down the road. For example, static analysis tools 
can flag code that may exhibit poor performance in certain situations. Examples 
of static analysis tools include FxCop for .NET and Coverity for Java. 


Some tools surface metrics about your code that may be correlated to quality, such 
as measuring cyclometric complexity. Cyclometric complexity refers to the num- 
ber of different execution paths through a piece of code. A method with a very 
large cyclometric complexity can be hard to understand and prone to bugs. 


Some tools, such as Code Climate Quality, are available in the GitHub Marketplace 
and can perform automated code reviews looking for common problems in code. 
This tool can identify files and sections of code that are changed frequently. 
Frequent changes often indicates that the code may have quality issues. Under- 
standing where your code churns often helps you focus your attention on changes 
to that code. 


Project Boards 
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Project boards are a useful way to visualize the progress and tasks for a project. 
Chapters 3 and 4 walk through setting up a project board along with project auto- 
mation for a repository. For a given repository, a project board serves as a com- 
mon source of truth. Everyone can look at a project board and have a good idea of 
the overall progress at a glance. 


However, you may consider using individual project boards that are not associated 
with a single repository as a means of managing your overall set of tasks on 
GitHub. You can go to https://github.com/new/project to create a new 
personal project board. 


Project boards come with a limited set of automations. To really customize your 
workflow, you may want to create a GitHub Action (see Chapter 14). With GitHub 
Actions and the GitHub API, it’s possible to create project board automations for 
nearly any workflow you can think of. 


GitHub project boards are not the only option for a Kanban-style board that works 
with GitHub. Trello (see Chapter 14) is another option. A few other options with 
deeper integration with GitHub include ZenHub, waffle.io, and HuBoard. 


Regardless of the one you pick, a good project board is a helpful addition to any 
software developer’s workflow. 
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IN THIS CHAPTER 





» Discovering how to be a participant 
that OSS maintainers value 


» Fostering a community that brings 
the best out of contributors 


» Encouraging an overall community of 


respect and collaboration that is 
welcoming 


Chapter 20 


Ten Tips for Being an 
Effective Community 
Member 


s of November 2018, more than 31 million people are on GitHub. That’s a 

lot of people. It can be difficult to stand out among such a large sea of 

people. But the truth is, most people starting out on GitHub don’t really 
understand how to be effective. They don’t understand the rules of the road to 
being a great member of the community. 


In this chapter, we compile ten tips that will help you be a wonderful community 


member — the type of person that every maintainer is excited to have involved 
with their repositories. 


Be Respectful and Kind 


Maintaining a repository can be a frustrating affair — especially when it’s a pop- 
ular repository and you’re volunteering your free time to an open source project 
and you’re about to answer the same question for the hundredth time. It’s 
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WARNING 





REMEMBER 


Report Bad Behavior 


TIP 


understandable that you may be very curt to the next person who asks the same 
question. It’s a waste of your time, and they didn’t do their due diligence to search 
to see whether the question was already answered. 


Resist the temptation to lash out. For that person, it may be the first time they’ve 
ever created an issue. They may not have read this chapter yet and learned how to 
be effective on GitHub. Your response will set the tone for their experience of your 
project and, perhaps, of GitHub as a whole. 


Be respectful and kind, and you may win over someone who will become a lifelong 
contributor. And even in the face of rudeness, remember that we all have bad days. 
You’ve probably done the same in the past yourself. The Internet can be very 
impersonal when communicating in writing. Sometimes a little kindness at the 
right moment reminds people that a human is on the other side and there’s no 
need to be rude. 


But to be clear, killing them with kindness is fine for the occasional rude behavior, 
but you should not have to tolerate abusive behavior. 


Whether bad behavior is directed at you or others, it’s important to the health of 
a community that we remain vigilant and report it. If you encounter or witness 
abuse on GitHub, report it at https: //github.com/contact/report-—abuse. 


It can be difficult to know the difference between someone just being slightly rude 
and someone being abusive. GitHub’s Terms of Service help spell it out. If you’re 
unsure, know that GitHub’s support people are well trained to draw this distinc- 
tion and will not react in a knee-jerk fashion to your report. 


Abuse isn’t the only type of issue you may want to report to GitHub. You can 
report harmful content, privacy concerns, and copyright claims from GitHub’s 
contact page at https: //github.com/contact. 


Write Good Bug Reports 
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For a repository maintainer, few things are more frustrating than an issue that 
looks something like this: 


The thagomizer isn’t working, fix it! I tried it out, and it doesn’t work. 
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TIP 


This example may seem extreme, but vague bug reports that are not actionable are 
unfortunately quite common. It doesn’t take too much effort to write a bug report 
that is helpful. 


When you come across a bug report where you have some expertise, don’t respond 
with “Works on my machine” with no other follow-up. Confirming that it works 
on your machine is actually beneficial, but it is more helpful to offer suggestions 
for what may be different between your machine and the person who filed the bug 
report. For example, you may want to let the person know which version of the 
software you have installed or if you have any other setup that may affect the 
situation. 


Sometimes, the best bug report is the one that isn’t written. Before you create an 
issue, search the issue tracker to see whether someone else already reported the 
bug. If they did, you may want to add further details to the issue if you see any- 
thing missing. 


Assuming you didn’t find the issue, it’s time to create a new issue. If the reposi- 
tory has an issue template, you should follow the template as closely as possible. 


If is the repository has no template, the following is a good format to follow: 


1. Describe the observed behavior. 

Try to be objective and communicate facts, not opinions. 
2. Describe what you expected to happen. 

How did the observed behavior differ from your expectations? 
3. Describe detailed repro steps. 


This step is the most important part of the bug report. Describe step by step 
how someone else can reproduce the problem. Try to make the repro steps as 
minimal as possible. When you encountered the bug, you may have taken ten 
steps to get there. But it may be possible to reproduce the bug in only five steps. 
Spending a little time to make sure that you remove any extraneous steps goes 
a long way into making a good bug report. 


4. Describe the repro environment. 


This step is where you describe the environment where you reproduced the 
bug such as the operating system and browser. While it's not necessary to try 
to reproduce the bug in other environments, repository owners are very 
appreciative if you do and report on the results. 
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Be Responsive 


REMEMBER 


TIP 


No matter how good your issue write-up is or your pull request code is, chances 
are the repository maintainers will have some follow-up questions. It’s particu- 
larly frustrating for a maintainer to ask for more information only to be greeted 
by crickets. If you submit an issue, don’t ghost on it. Make sure you make time to 
follow up and respond to questions from the maintainers. 


And the shoe fits both ways. If you are a maintainer, try and be responsive to 
people who submit issues and pull requests. In some cases, using an automated 
response to an new issue or pull-request is appropriate if your repository is par- 
ticularly busy. For example, you could use a Probot app to automatically respond 
to new issues and pull requests with a note letting them know you plan to look at 
it but that it may take some time. 


Being responsive doesn’t necessarily mean you take care of everything right away. 
It means that you set expectations right away. On either side of the comment, 
whether you’re a contributor or a maintainer, the only way for the other person to 
know when to expect changes is if you tell them. Working on remote, asynchro- 
nous projects depends heavily on communication. When you’re in an office you 
can see whether someone doesn’t come in to work for a while and know they are 
probably on vacation; on GitHub, you don’t have that contextual awareness. 


As an added form of communication, keep your profile status up to date if you do 
plan on going on vacation. For more detail, see Chapter 16. 


Submit Pull Requests to Correct 
Documentation 
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The campsite rule states that one should leave a campsite in better condition than 
they found it. It’s a good rule to follow not only with campsites, but also with 
documentation. 


Good documentation is often the weak point with an open source projects. Many 
OSS projects have very few volunteers, and much of their time is taken working on 
the actual code. This lack of support makes repository maintainers especially 
appreciative when someone comes along and contributes to the documentation. 


Getting involved with improving a repository’s documentation is also a great way 
to dip your toe into OSS. If you happen to find an error or something missing in a 
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project’s documentation, consider submitting a pull request to the project fixing 
the error. This contribution leaves the overall OSS ecosystem better off than it was 
before. 


One of the most challenging pieces of documentation to keep up to date is the Get- 
ting Started docs that contributors are meant to follow to first get the project 
setup on their machine. It’s challenging because the maintainers rarely set up the 

REMEMBER project brand new, unless they get a new machine. As you’re following the steps, 
don’t be afraid to open a pull request on this documentation if you had to do 
something different. It can be especially helpful if instructions are different on 
Mac versus Windows versus Linux and you’re on a machine that the project 
doesn’t have documentation for yet. 


Document Your Own Code 


Documenting your own code goes a long ways toward making it more accessible 
to others. Trying to use unfamiliar code can be challenging and time consuming. 
Good documentation can save people a lot of time and get them up and running 
with your code quickly. If only 12 people use your code and you save them each one 
two hours of hassle, that’s a full day saved! 


Depending on the platform, many tools generate documentation from comments 
in code. Javadoc is a famous example for Java code. It requires that you comment 
public methods and classes with a standard format. By following the format, you 
can use the Javadoc tool to generate HTML files. JSDoc is another one for 
JavaScript. 


In addition to code documentation, consider other documentation such as 
the ones we cover in Chapter 9. For example, every repository should have a 
README.md file that describes what the repository does. It should also have a 
CONTRIBUTING. md file that describes how to contribute. 


Give Credit Where It’s Due 


Most open source licenses require proper attribution if you make use of the code 
in your own project. If you use some source code from an open source project, giv- 


ing credit where it’s due is a legal matter and required by the license. 
WARNING 
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But to be an effective community member, credit doesn’t end with attribution to 
comply with a license. In many situations, giving credit demonstrates that you are 
a classy person. 


For example, if someone contributes a feature or bug fix, mentioning the person 
who fixed it in your release notes is a good idea. For example, GitHub Desktop 
makes a point to thank people using its GitHub handles and links to the pull 
request that contributed a fix in its release notes at https: //desktop.github. 
com/release-notes/. 


Another great way to give credit is to mention the person who opened an issue 
that you may have fixed with a pull request. The pull request description will most 
likely link to the issue, but calling out the person who found the issue in the 
description is a great way to encourage others to continue to help find bugs. 


Help Get the Word Out 


REMEMBER 


Many open source projects are small and relatively unknown. If you find a project 
useful, help get the word out. It not only benefits the project, who may get an 
influx of new users and contributors, but it benefits the people you tell who may 
need that very tool. 


You don’t need a huge platform to help people get the word out. Maybe your 
Twitter follower count is relatively small. Don’t let that stop you. The power of 
network effects can sometimes help a message really take off. 


If you write blog posts or publish YouTube videos, you can also mention different 
projects, your impressions, and maybe even a tutorial on them on these mediums. 
The goal here is to help people and projects meet. 


Be Proactive and Mentor Others 
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GitHub’s community is growing rapidly. New developers are being minted every 
single day. What this means is a lot of beginners will be on the site. Over time, you 
will start to accumulate experience that would be very valuable to one of these 
beginners. Be proactive and offer to mentor others. 
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For example, if you maintain an open source repository and see that someone is 
struggling to make a contribution, offer to walk them through the process. Point 
them to resources and help them along. If you help two people become proficient 
contributors and community members and they each help two people down the 
road and so on, you could end up having a huge impact on the community. 


Sometimes it can even be effective to jump on a video chat and help someone 
debug their code in real time! If you’re comfortable with this approach, it can be a 
great way to meet new people and see for yourself how someone new approaches 
your project. It may provide insight into how to improve your documentation. One 
of our favorite video chat services to use for this purpose is https: //appear . in. 
It’s a free, in-browser video chat service that allows for multiple attendees and 
allows you to share your screen. 


Contribute Outside of GitHub 


Many open source projects have a lot of activity outside of GitHub. Contributing to 
the community can go beyond creating issues and opening pull requests. For 
example, as you gain expertise in a topic, consider heading over to StackOverflow. 
com and answering questions on that topic. Many open source projects have chat 
rooms associated with the project in Slack or Gitter. It’s a benefit to others if you 
head over there and offer your ideas. 


Talk to maintainers about other ways you can support their work. As you grow in 
your career as a software developer, you will pick up skills that are valuable to an 
OSS project. For example, you may help them figure out how to sign a package 
using Let’s Encrypt. You may help them register a domain name and pay for it. 
You may help them navigate setting up a Docker container so that others can try 
out their project with less setup fuss. 


Whatever it is, don’t be shy in offering your skills in support of open source proj- 
ects, especially those that you benefit from. 
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“Building an Inclusive Code Review Culture,” 151 
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.NET Fringe (website), 287 
.NET São Paulo (website), 286 
network, of repositories, 206 
Network tab, 314 

Node.js repository, 160 


notifications, managing with Octobox, 225-227 


Notifications icon (GitHub.com), 30 
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blocking users, 176-177 
creating open source repository, 169-173 
ending projects, 185-187 
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finding places to contribute, 161-163 
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labeling issues, 179-180 
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setting contributor expectations, 166-167 
starting your own, 169-187 
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transferring ownership, 186-187 
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browser to repository, 124 
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pull requests, 135-140 
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settings for, 197-199 
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adding contributor guidelines, 173 
adding licenses, 170-172 
archiving projects, 185-186 
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creating open source repository, 169-173 
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issue templates, 181-183 
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saved replies, 183-184 
setting contributor expectations, 166-167 
starting your own, 169-187 
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tracking projects, 167-168 
transferring ownership, 186-187 
triaging issues, 180-181 
writing documentation, 178-179 
writing README .md files, 178 
ownership, transferring, 186-187 
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packages (Atom), 37 
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about, 64 
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finding resources for, 76 
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Performance and Memory tab, 315 
permissions, verifying for repo, 79-80 
personal access tokens, 25 
personal info, for profile, 277-278 
personalizing 

about, 251 

GitHub Actions, 260-262 

GitHub apps, 255-259 

GitHub.com accounts, 18-25 

Probot, 255-259 

using browser extensions, 251-254 
picture, for profile, 277 
pinned repositories 

about, 161 

on profile, 278-279 
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Popular Topics section (Explore page), 158-160 
PowerShell, 9 
power-up 
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installing GitHub, 220-222 
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preferences (Atom), 37 
preparing contributions, 83-90 
privacy, of code, 189 
Pro badge, 278 
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Probot, 255 
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profile 
about, 32, 275-276 
bio, 277-278 
contribution activity, 281 
contribution graph, 279-281 
GitHub.com, 18-19 
personal info, 277-278 
picture for, 277 
pinned repositories, 278-279 
status message, 277 
Profile setting, 197 
project boards 
about, 56-62, 316 
creating, 56-60 
reviewing, 81 
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apps, 266 


projects 
accessing existing, 77-83 
archiving, 185-186 
ending, 185-187 
milestones for, 207-208 
orienting yourself with existing, 80-83 
specifying, 139 
surveying for contribution, 164-165 
tracking, 167-168 
Projects setting, 198 
Projects tab, 45-46 
project-specific documentation, 302-303 
prototype user interfaces, 313 
public setting, 17 
publication, of branches, 86-89 
Publish dialog box, 240 
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publishing repositories in GitHub Desktop, pulse, of repositories, 204 
124-125 pushing code to GitHub, 134-135 
Pull Request button, 233 pwd command, 10 
pull request list (GitHub Desktop), 72 
pull requests 
about, 133 Q 
adding reviewers, 138 question label, 180 
checking out, 230-233 question-mark, 43 
clear purpose of, 141 Quick pick icon, on GitHub.com, 30 


commenting on code, 146-148 
creating, 139-140, 230-233, 244-246 R 
creating in Visual Studio, 244-246 
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code of conduct, 165 
contributing code guide, 164-165 
CONTRIBUTING. md file, 164 

focus of, 141 through issues, 81 

Git Alias and, 137 README . md file 

in GitHub.com, 30 modifying, 48-53 

images in, 142-143 reading, 80 
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interacting with in VS code, 237-238 ready for review label, 180 
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opening branch Compare page, 137 Remembericon3 


opening GitHub.com from Terminal, 137 
pushing code to GitHub, 134-135 


remote, 102 
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reviewing, 81, 144-151 cloning, 71-72, 99-100 

reviewing changed files, 146 cloning in GitHub Desktop, 71-72 
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reviewing in Visual Studio, 244-246 
specifying assignees, 139 
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specifying projects and milestones, 139 
submitting, 320-321 exploring, 44-47 

suggesting changes to, 148-150 finding resources for GitHub Pages, 76 
viewing, 230-233, 244-246 forking, 97-112, 100-112 

viewing in Visual Studio, 244-246 GitHub, 35 

writing, 140-144 
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creating, 113-114 
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insights of, 204-207 
issues, 56-62 
linking, 70, 93 
making public, 173-174 
merging pull requests, 53-56 
modifying README.md, 48-53 
open source, 38, 169-173 
opening browser to, 124 
opening in Atom, 74 
pinned, 161, 278-279 
project boards, 56-62 
publishing in GitHub Desktop, 124-125 
setting up, 41-44 
setting up a personal website, 66-69 
setting up local environment, 71-75 
setup, 63-76 
starring, 161, 281-282 
subscribing to in Slack channel, 214-216 
tabs, 45-46 
top information, 44-45 
tracking in GitHub Desktop, 123-124 
trending, 157-158 
turning a project repo into a website, 64-66 
turning into a website, 64-66 
verifying permissions for, 79-80 
viewing for GitHub organizations, 192-193 
website, 64, 234 
Repositories setting (GitHub.com), 23 
repository list (GitHub Desktop), 72 
Repository topics setting, 198 
researching pull requests, 151 
resolving merge conflicts, 89-90 
resources, 25, 76 
responding 
to comments, 83 
with kindness, 175 
responsiveness, 320 
reviewers, adding, 138 
reviewing 
changed files, 146 
project boards, 81 


pull requests, 81, 144-151, 244-246 
pull requests in Visual Studio, 244-246 
Ruby, 304-305 
running tests automatically, 311-312 
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Saved replies setting (GitHub.com), 24 
saved reply, 183-184 
scaffolding apps, 313-314 
SCM (source control management), 8 
SD Ruby (website), 286 
Search bar, 28 
sections 
adding to personal websites, 91-92 
adding to websites, 69, 91-92 
security 
for apps, 268 
reviewing code for, 146 
security category, for tools and apps, 266 
Security setting, 23, 198 
selfies, 254 
Sessions setting (GitHub.com), 23 
setting(s) 
contributor expectations, 166-167 
GitHub organizations, 197-199 
Settings tab, 46 
setup 
collaborative coding environment, 27-38 
GitHub Desktop, 34-35 
GitHub repo, 63-76 
local environment, 71-75 
personal website repo, 66-69 
repository, 41-44 
Sign in dialog box, 34-35 
signing up, for GitHub.com, 17-18 
Slack 
installing GitHub app for, 212-214 
subscribing to repositories in, 214-216 
trying integration with Slack, 217-219 
websites, 212 
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software licenses, 43 
source control management (SCM), 8 
Sources tab, 314 
speaking, at events, 292-293 
specifying 
assignees, 139 
labels, 139 
milestones, 139 
projects, 139 
Squirrel icon (Atom), 36, 37 
SSH key, 22-23 
StackOverflow, 315 
staging changes, 117-118 
stale issues, closing, 83 
Star button, 45 
starred repositories, 161, 281-282 


starting your own open source software (OSS), 
169-187 


status command, 11 

status message, for profile, 277 
STRIDE, 146 

submitting pull requests, 320-321 


subscribing to repositories in Slack channel, 
214-216 


suggesting changes to pull requests, 
148-150 


summary, in commit messages, 121 
support category, for tools and apps, 266 
surveying projects for contribution, 164-165 
sync project button 

Atom, 75 

GitHub Desktop, 73 
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tabs, repository, 45-46 
taglines 
changing for websites, 69 
modifying on personal websites, 91 
team discussions, 200-201 
Team for Open Source tier, 190 
Team tier, 190 
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about, 199 
creating parent/child, 199-200 
creating within GitHub organizations, 195-196 
defined, 190 
Teams setting, 198 
Teams tier, 192 
templates, for issues, 181-183 
Terminal app 
defined, 9 
finding, 9 
opening GitHub.com from, 137 
trying Git on the, 9-14 
testing 
apps, 273-274 
GitHub Actions, 262 
testing category, for tools and apps, 266 
TestQuality app, 274 
Things you're watching link (GitHub.com), 21 
Third-party access setting, 198 
Tip icon, 3 
titles 
changing for websites, 69 
changing on personal websites, 91 
track, 289 
tracking 
projects, 167-168 
repositories in GitHub Desktop, 123-124 
traffic, of repositories, 205 
training, in-person, 301-302 
transferring ownership, 186-187 
Trello, 219-225, 316 
trending repositories, 157-158 
triaging, 81, 82-83, 180-181 
trial and error, 297-298 
Try.NET (website), 305 
Tsc-watch for TypeScript, 312 
tutorials, online, 305-306 
tutorials, online coding, 304-305 
Twitter, 306-307 
two-factor authentication, 23, 190 
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-u flag, 135 
Unity 
using GitHub for, 239-242 
using GitHub for Unity in, 240-242 
Up for Grabs (website), 162 
updates, for Atom, 36 
upstream 
about, 102 
contributing changes to, 104-107 
fetching changes from, 103 
user experience, for apps, 267 
user groups, 286 
user interface, prototype, 313 
username, changing, 19 
users, following, 282-283 
utilities category, for tools and apps, 266 
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Verified domains setting, 198 
verifying permissions for repo, 79-80 
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about, 8 
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vetting process, for GitHub Marketplace, 267-268 


viewing 
issues, 233-234 
pull requests, 230-233, 244-246 
pull requests in Visual Studio, 244-246 
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Visual Studio Code 
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VS Code. see Visual Studio Code 
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Anita Borg institute, 294 
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Atom documentation, 38 

Atom Flight Manual, 38, 74, 234 
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Atom packages, 37 

Atom project forum, 304 
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“Building an Inclusive Code Review 
Culture,” 151 


building personal, 91-93 
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Cheat Sheet, 3 
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Code of Conduct, 307 
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Contact page, 299 
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creating issues for, 69-71 
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dependency security vulnerabilities, 205 
descriptions, 160 
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documentation example, 179 
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example commits, 122 
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Git Docs, 14 
Git documentation, 132 
Git for Windows, 9 
Git Merge, 292 
GitHub, 4 
GitHub API, 25 
GitHub blog, 4, 307 
GitHub Community Forum, 25, 307 
GitHub Constellation, 292 
GitHub contact page, 25 
GitHub Contact page, 318 
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GitHub Desktop open source project, 80 
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GitHub for Unity extension, 242 
GitHub for Visual Studio extension, 246 
GitHub for VS Code pull requests extension, 238 
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workflows, GitHub Action, 260-262 
writing 

blog posts, 70 

bug reports, 318-319 

code, 113-132 

commit messages, 120-122 

documentation, 178-179 

pull requests, 140-144 
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